Helping to maintain a project is the best way to contribute to its overall health.
- Triaging Issues
- Making Bugs Actionable
- Reviewing Stale Issues
- Making Issues Available
- Following up on In-Progress Work
- Adding a Patch
- Pushing to a Branch
We encourage the community to help make bugs actionable, make features available, and close stale issues. Triaging is one of the most important contributions a community member can make for a project's health. Steve Klabnik's article on how to be an "open source gardener" reflects our values here at debugger.
When bugs are filed, they are immediately labeled not-actionable. Before they can be appropriately addressed by our contributors, bugs need to be made actionable.
You can help us make bugs actionable by following these steps:
- Check for duplicate bugs.
- Verify that the bug is reproducible.
- Define steps to reproduce the bug, with expected and actual results.
- Create a small test case. We have a glitch template for sharing examples.
- Add labels.
We define stale as issues that are 30 days or older. If an issue is stale, it is often an indicator that the issue is problematic in one or more ways.
Typically, a stale issue can be:
- Unnecessary: It does not signal a problem that needs to be solved.
- Vague: It doesn't explain the problem well.
- Broad: It signals too many problems at once.
- Low priority: It signals a problem that could be solved, but is not urgent.
Here's how you can help review each of these types of issues:
- Unnecessary issues - Close them.
- Vague issues - Clarify these issues with the contributor(s) who opened them, and try to pinpoint the problems that need solving.
- Broad issues - Divide larger issues into several smaller, more focused issues.
- Low priority issues - Close them and tag them with the icebox label.
debugger is a highly active repository. There are too many issues open in the project at any one time for us to be able to complete them all in a timely manner.
We try to prioritize the issues into three buckets: current milestone, backlog, and icebox.
- We add the current milestone label to issues that we expect to accomplish within the next two weeks.
- We add the backlog label to issues that we would like to accomplish in the next four to six weeks.
- We add the icebox label to issues that we would like to get to in the future. However, to keep these issues from flooding the issue page on the repository, we close them temporarily until they can be dealt with. We commit to reviewing the icebox issues every six weeks, and reopening the issues that fit the current milestone or backlog labels.
In addition to the above, there will always be some issues that do not fall into the above buckets:
- Issues that have not been investigated by a maintainer.
- Issues that we believe realistically could be handled by a community member (e.g. UI polishing, code health, etc.).
In order for an issue to be marked available, it must meet two requirements.
Available issues must have:
- A clearly defined specification (end-state).
- A clear implementation plan.
Our goal is to have 100% of our issues either available or blocked by another available ticket.
If you find an issue that is not available, you can:
- Investigate the issue, and brainstorm solutions to any problems you may find.
- Share questions, or offer reasonable solutions that can be implemented.
- Add a patch that will help anyone who picks up the issue in the future.
Following up on in-progress work is a delicate, but tremendously important task.
When done well, the person whom you follow up on feels appreciated and supported. When you check in with them, they will often feel comfortable asking questions that could be blocking their work. If you, the contributor, and any other community members can find answers to these questions, the work can move forward, and the debugger can improve.
When done poorly, the person whom you follow up on feels rushed, micromanaged and second-guessed. Contributors made to feel this way will often struggle to complete their work, and they will be reluctant to ask for help.
Here at debugger, it is important that follow-ups go smoothly, and that all contributors involved feel appreciated and well-supported.
Here are a few good rules of thumb that will help you follow up on in-progress work in a structured, respectful way:
- Ask the contributor what the timeline is for completing their task(s).
- Ask the contributor if any part of the task(s) has them feeling stuck.
- Offer to pair up and work together, or to discuss the task(s) via Slack or voice chat.
- Work together to break down each task into small pieces, so that things can be merged gradually, instead of all at once.
Patches are a great way to clarify what work needs to be done.
Patches on available issues help clarify where the necessary code should eventually go. Also, they are often clearer than English.
Here are a few ways you can add a patch:
- Write some pseudocode, or add comments where you think new code should go.
- Add a diff, using diff code blocks.
- Use the [gist] cli to make diffs. Use a shortcut for
git diff | gist --type diff. - When gists are long, leave a comment on the issue with a link to a gist, along with this snippet:
curl <raw-gist-url> | git apply.
Here are the steps for getting a PR branch and then updating it:
Getting Set Up:
- HTTP Remote github help
- Two-factor Authentication (2FA) github help
- Personal Access Tokens github help
Steps:
git remote add <username> https://github.com/<username>/debugger.git
git fetch <username>
git checkout --track <username>/<pr-branch>
git pull --rebase # if you want to get new changes
git push <username> <pr-branch>
git push -f <username> <pr-branch> # sadly, you often need to push force- Don't worry about including
--force, it's often inevitable if you're helping with a rebase. - It's best to include your work as a separate commit, so that the contributor can easily see the patch.