Skip to content

Latest commit

 

History

History
139 lines (94 loc) · 5.48 KB

maintainer.md

File metadata and controls

139 lines (94 loc) · 5.48 KB
Raw

Maintainer Tips

Helping maintain a project is the best way to contribute to its overall health.

Triaging Issues

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 projects health. Stave Klabnik's article on how to be an open source gardener expresses our values.

Making Bugs Actionable

Bugs are labeled not-actionable when they are filed. Here is a checklist for making bugs actionable:

  1. Check for duplicate bugs
  2. Verify that the bug is reproducible
  3. Define steps to reproduce with expected and actual results
  4. Create a small test case. We have a glitch template for sharing examples.
  5. Add labels

Reviewing Stale Issues

We define stale as issues that are 30 days or older. Stale is often an indicator of another issue: it is unnecessary, too vague, too broad, or a low priority.

  • unnecessary - close it
  • vague - clarify the issue and make it more available
  • broad - create more focused issues, such as "add flow types to WhyPaused component"
  • low priority - close it and add the icebox label to it.

Prioritizing Issues

At any given point, there are too many issues in the project to realistically be able to complete them all in the near future.

We try to prioritize the issues into 3 buckets: current milestone, backlog, and icebox.

  • We add issues to a milestone every two weeks that we hope to accomplish in that time frame.
  • We add the backlog label to issues that we would like to accomplish in the next 4 to 6 weeks.
  • We add the icebox label to issues that we would like to get to in the future. We also close these issues so that we can keep the issue list under control. We commit to reviewing the icebox issues every six weeks and re-opening issues we hope to get to.

There will always be some issues that don't fall into these buckets.

  • We have not yet investigated the issue
  • We think a community member could realistically do it e.g. ui polish, code health

Icebox Issues

Making Issues available

Available is short for two things:

  1. a clearly defined specification (end-state)
  2. a clear implementation plan

Our goal is to have 100% of our issues available or blocked by another available ticket. If you find an issue that is not available you can:

  1. investigate the issue and answer questions that you have
  2. share questions or offer reasonable solutions that can be implemented
  3. add a patch to help the person who picks up the issue

Following up on In Progress work

Following up on in progress work is delicate, but tremendously important.

When done well, the recipient feels like their work is appreciated and feels comfortable asking questions that could be blocking the work.

When done poorly, the recipient feels like they're being rushed and is not sure how to complete it.

Some good rules of thumb are:

  1. asking what their timeline is
  2. asking if they are blocked or if you can help
  3. offer to pair or talk on Slack.
  4. try to breakdown the work so small pieces can be merged

Ship

I recommend ship for tracking issues.

Adding a patch

Patches are a great way to clarify what work needs to be done.

Patches on available issues help clarify where the code should go and are often clearer than English.

Tips:

  • write some pseudo-code or add comments where code should go
  • add a diff with diff code blocks
  • use the [gist] cli to make diffs. I have a shortcut for git diff | gist --type diff
  • when gists are long you can include a link to a gist and this snippet in the issue curl <raw-gist-url> | git apply

Pushing to a branch

Here are the steps for getting a PR branch and then updating it

Getting Setup:

  1. http remote github help
  2. 2fa github help
  3. personal access tokens github help

Steps:

git remote add <username> https://github.com/<username>/debugger.html.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

Notes:

  • Don't worry about including --force, often it's inevitable if you're helping with a rebase.
  • It's best to include your work as a separate commit so the contributor can easily see the patch.