Difference between revisions of "Github Issues"

Revision as of 12:44, 30 July 2014

Logging bugs

DO NOT use this process for security issues or non-code (e.g. documentation) bugs.

1. Go to the dw-free repository's Issues. (You can get there by going to the main dw-free repository, then looking on the right-hand sidebar for the "Issues" link.)

2. Do a quick skim over the existing issues to see if yours is a duplicate. (Right now, finding things is harder than it will be: adding more tags to help significantly with categorization and search is my next major task, but again, I wanted to get this posted as quickly as possible. In the meantime, it's okay if we get a few dupes.)

3. Open an issue if you don't see one already existing for what you want to report. To open an issue, use the green button in the upper right hand corner, before the list of open issues, labelled "New Issue".

4. For "Title", put something both concise and descriptive: what's the one-sentence summary of the task? When in doubt, make the first word an active verb ('remove', 'update', 'fix', etc) and make the sentence itself imperative: "add missing link on update page", "correct display issue in Celerity on community pages", "change text on crosspost tab of Manage Settings to reflect new workflow", yadda.

5. For the larger "Leave a comment" box, describe the issue as thoroughly as you can: steps to reproduce, details of what needs to be changed, what it's doing that it shouldn't do, what it should do that it isn't doing, what would be necessary for the bug to be considered 'fixed', etc. This might be a few sentences, or it might be a few paragraphs. Whatever it takes to give enough detail that someone coming along to work on it can understand the bug and be reasonably confident in tackling it.

6. When you're done, hit 'submit new issue'.

Finding bugs to work on

1. Go to the dw-free repository's Issues. You'll see all the current open issues. This view is a bit of a muddle, with claimed/unclaimed issues all lumped together and pull requests lumped in with the issues.

2. Fortunately, there are labels and milestones! We've done our best to come up with a collection of labels and milestones that will be useful for people to search with, and we're going to keep refining them. (We may, for instance, convert the unclaimed/in progress/pull request milestones into labels instead, freeing up milestones for "which major ongoing project, if any, does this belong to", if it turns out to work better that way.)

3. For now, though: to see all unclaimed bugs, go to milestones (top left 'tab', next to the 'browse issues' tab) and select Unclaimed. Once you've selected the "Unclaimed" milestone, use the labels on the left hand side of the results page to further refine what you want to browse. You can go for "unclaimed issues that are labeled lower-effort", or "unclaimed issues that are bugs", and you can combine labels by clicking on them to get unclaimed issues that are both bugs and major severity.

4. Once you've found something you want to work on, load the issue. Leave a comment saying "I'll claim this" (so that people can know at a glance that it's spoken for without having to look at the milestones, so I know to change the milestone).

5. Go through the normal process of creating a branch, making your changes, testing your changes, committing your changes to your branch, opening up a pull request, etc. In your commit message for when you commit your changes, include the sentence "Fixes issue #XXX", where #XXX is the issue number. (You can find the issue number after the title of the issue on the issue detail page, on the right-hand side of the issue on the "all issues" page, or -- if all else fails -- in the URL of the issue. For instance, "Update in-repository documentation to point to GHI instead of Bugzilla", an issue I opened this morning, is issue #663: this is listed after the title on the issue detail page, and at the end of the URL for the issue detail page.)

6. If you want to be exceptionally helpful and make life easier for Fu, leave a comment in the pull request with a link to the originating issue, and leave a comment in the originating issue with a link to the pull request!

Claiming an issue

You can claim an issue by leaving a comment with the words "claim", "claimed", or "claiming". Case doesn't matter -- you can use capital letters if you want. You can also have other words be part of the comment, so you don't need to memorize a specific format. "I'm claiming this" will work just as well as "Claimed!"

Claiming will only work if the current issue is not yet claimed -- this will avoid the problem of accidentally grabbing the bug from someone else during a long discussion about claiming something else in a different context.

You do need to be part of the Dreamwidth contributors team on Github before assigning issues will work. If you're a new contributor, you'll be automatically added when you send in your Contributor Licensing Agreement.

For existing contributors, do double-check if you're on any of the Dreamwidth teams. If it shows you a list of teams you're on, you're good! If we missed you somehow and tells you that you're not on any teams, let us know and we'll add you ASAP.