Walkthroughs in the Windows Terminal Repository

Mike Griese

September 5th, 20230 3

Note: You can also watch a video version of this blog post on Open at Microsoft.

Driving open-source contributions in large projects can be a challenge. As a new contributor, you might have a great idea for a new feature, or want to help fix a nagging bug, but you don’t know where to start. Even with a small project, it can be difficult to find the right place to start writing code.

As a maintainer, you might know exactly where to start working on a feature or a bug fix. You might even have a good idea of how to implement it. But, you don’t have the time to write up a detailed guide for every feature. How then, can you share this mental map of the problem space with the community effectively, so they could pick up an issue right where you would? That’s where walkthroughs come in.

Walkthroughs are a new thing we’re experimenting with on the Terminal repo. They’re not meant to be full guides to how to fix the issue. Instead, they’re meant to be a starting point for contributors to get started on a feature or bug fix. They’re meant to be a way for maintainers to share their knowledge of the codebase with new contributors. A way of sharing our “mental map” of the codebase.

Walkthroughs are usually a very high-level overview of how we might get started on a task. Often, we just start with a list of files, method names, struct definitions. We might even include a few code snippets, or relevant PRs that add something similar, as “prior art”. The goal is to give contributors a starting point for their own research.

Example Walkthrough

This is an example of what one of our walkthroughs might look like. This example is from this comment – a real walkthrough that turned into a feature in the Terminal. That thread originally covered a request to add a “Close pane” entry to the tab’s right-click context menu.

  • I’d start by taking a look at TerminalTab::_CreateContextMenu, in TerminalTab.cpp. That’s what we use for building all the other context menu entries for the tabs, so that’s a good place to insert a new one.
  • I’d stash the Controls::MenuFlyoutItem that you make for ClosePane into the TerminalTab itself as a member. That way, we can use that member to toggle the visibility when the number of panes in the tab changes.
  • I’d start by setting the item to be Visibility(Collapsed), so that it’s not initially visible.
  • TerminalTab::SplitPane is where new splits get added, so that would be a good place to change the Visibility to Visible
  • in TerminalTab::_AttachEventHandlersToPane, we add a pane->Closed callback, which we could use to set the Visibility back to Collapsed if there’s only one pane in the tree.

We generally keep walkthroughs high level. They’re supposed to be quick writeups of how we would get started, not a full guide. We try to encapsulate our first thoughts on where we’re start looking to solve the issue. This usually involves mentioning a relevant place to start. This might be a specific file or method to look at. In this case, we’re calling out TerminalTab::_CreateContextMenu specifically. That immediately clues the reader in to a file and a place to start reading the code. Now, they don’t need to look over the codebase to figure out how the tabs are abstracted, or how the context menus are built. They can just start reading the code from that method. Mentioning specific APIs can also be helpful, to draw the contributor’s attention to an API they might not have known about, but we know we’ll need.

From here, it is up to the contributor to figure out the rest. Sometimes, unexpected quirks might come up during the development process that weren’t mentioned in the walkthrough. That’s fine, that’s normal! That’s how software is written. We probably would have run into the same issue too. If the contributor can figure them out on their own, that’s great. Otherwise, they’re always free to drop a comment so we can work through the issue together.

GitHub Projects integration

Now that we’ve written up all these Walkthroughs, how can community members actually discover them?

We’ve created a specific GitHub Project for Walkthroughs. This project is linked from the Contributing Guide, or you can find it at

https://aka.ms/terminal-walkthroughs

GitHub project board

Projects give us the ability to add arbitrary fields to issues in project boards has been a huge help here. We’ve got a “difficulty” field to track how hard we think the issue is. We also have a status field to track which issues are good walkthrough candidates, or already written up. Plus, these fields remain a feature of the board itself, and not necessarily the broader repo. This avoids having “label soup” spill into the repo itself

On the first tab of the project, you can find a list of all the Walkthroughs we’ve written up, sorted by “difficulty”. The issues marked “Easy” are ones that any contributor who’s never contributed to the Terminal before should be able to help with. They usually have the most detailed walkthroughs, and are a great place to start. We’ve got some harder ones on there too. These often have more abbreviated walkthroughs, or are more complex features. They’re a great place to start if you’re looking for a challenge.

Community shoutouts

We’ve had a number of contributions all from walkthroughs over the past few months. Major shoutouts to the following contributors, who all contributed to the Terminal based on walkthroughs:

Conclusion

We’re really excited about the potential of Walkthroughs. We think they’re a great way to help new contributors get started on not just the Terminal, but any open-source project.

Interested in doing something similar for your own repo? This is actually surprisingly easy with GitHub Projects. Just click the “Make a copy” button in the dropdown button the project board.

image

That’ll let you create a copy of the project with all the same fields and boards, under a name of your choosing. You can then use that project to track your own Walkthroughs for your own projects.

Mike Griese Senior Software Engineer, Windows Terminal

Read next

0 comments

Discussion is closed.

Feedback usabilla icon