Difference between revisions of "Github Issues"

Revision as of 19:00, 7 June 2015

As of early 2014, we migrated from Bugzilla to Github Issues. Workflows for GHI are documented here in addition to the dw_dev community. For more details on git in its own right, see Git How To and Git Getting Started.

Signing up for Github

Github's guide on signing up for a new account. You can use a free personal plan to collaborate with Dreamwidth.

Logging bugs

DO NOT use this process for security issues or non-code (e.g. documentation) bugs. Any security concerns should be reported privately to our staff. Documentation issues are discussed in dw_docs.

1. Go to the dw-free repository's Issues. (You can also get there from the main page for the dw-free repository, 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. By default only open issues are shown, but you may also want to check closed issues for any recent fixes that might not be live on the site yet. (Right now, finding things is harder than it will be; we are planning to add more tags to help significantly with categorization and search. In the meantime, it's okay if we get a few duplicate reports.)

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, to the right of the search field, labelled "New Issue".

4. For "Title", put something both concise and descriptive: for outright buggy behavior, state what's going wrong. For usability issues, try to state the desired behavior, e.g., 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, click '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. If claimed, the Gravatar (user icon) of the user the bug's assigned to is displayed on the right-hand side of the issue bar.

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.

3. For now, though: to see all unclaimed bugs, hit "Assignee" on the Issues page and choose "Assigned to nobody". You can filter with multiple constraints: for example, you can find a handy list of unassigned issues that have been selected as suitable for beginning coders or people new to our codebase! Milestones are now used to designate major projects, so if you're looking for something small "no milestone" is a useful term to filter on.

4. Once you've found something you want to work on, load the issue. Leave a comment saying "I'll claim this" or similar - see below for more details!

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 #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 mention the originating issue number in the commit, github will automatically provide a link!

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.