Difference between revisions of "Github Issues"

Latest revision as of 14:15, 7 November 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.

Reporting Bugs

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 has already been reported. 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, the easiest way to find relevant issues is a full text search. We are planning to add more tags to help significantly with categorization and search, but in the meantime, it's okay if we get a few duplicate reports.)
   
   
3. Go ahead and open a new issue if you don't see an existing one that covers 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. In the case of outright buggy behavior, use a phrase that explains 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", and so forth.
   
   
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. Include links to any relevant support requests or discussions of the issue elsewhere. If you have a screenshot, you can include that as well.
   
   
6. When you're done, click 'Submit new Issue'.

Working on Bugs

1. If you're a new contributor, you'll need to send in your Contributor Licensing Agreement. Once that's received, you'll be added to the Dreamwidth contributors team on Github. If you've contributed in the past and are coming back after a hiatus, do double-check whether you're on the list of Dreamwidth contributors. If the button at the bottom of the left-hand table on that page says "Leave", you're on the team! (DON'T CLICK THE BUTTON.) If you're not listed, let us know and we'll add you ASAP.
   
   
2. To find an existing issue to work on, go to the dw-free repository's Issues. You'll see a list of all the current open issues. If already claimed, the issue should have the "status: claimed" label, and the Gravatar (user icon) of the assigned user appears near the right-hand side of the entry.
   
   
3. To see all unclaimed (available) issues, click on the "Assignee" dropdown below the search field, and choose "Assigned to nobody". You can filter with multiple constraints: for example, to see only issues without the label status:claimed (in the event that an issue has been claimed by someone to whom it has not been automatically assigned), or you can find a handy list of unassigned issues that have been selected as suitable for beginning coders or people new to our codebase! The labels page lists all of our current tags for issues, with links to search on each. Milestones are now used to designate major projects, so if you're looking for something smaller in scope, "no milestone" is a useful term to filter on. 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 over time. (See Curating Bugs below for more about the labels we use.)
   
   
4. Once you've found something you want to work on, load the issue. Leave a comment saying "I'll claim this" or similar - any comment with the words "claim", "claimed", or "claiming" will do, as long as you're on our contributors team, and the issue isn't already claimed by someone else. 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!"
   
   
5. After claiming the issue you're interested in, go through the normal process of creating a branch, making your changes, testing your changes, committing your changes to your branch, pushing the branch to Github, etc. (as documented in Git How To). Make sure you include the originating issue number in your commit message -- Github will automatically create a link to the issue, and even adds a link from the issue page to your changes! 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.
   
   
6. Submit a pull request to have your changes reviewed and eventually accepted into the main develop branch. In the description field of the pull request form, it is very important to include the phrase "Fixes #XXX", where #XXX is the issue number. Including this in the description (not the title!) of the pull request accomplishes two things: it automatically assigns the related issue to you if you didn't do that earlier, and it automatically closes the issue when the pull request is merged. For more information about automatically closing the related issue, see Closing issues via commit messages on Github.

Curating Bugs

Because most contributors don't have the necessary permissions to label issues directly using Github's web interface, afuna wrote a monitoring service (bot) to add labels to issues in respond to comments. These are the label comments currently recognized by the system:

##curated: beginner

##curated: mostwanted

Used by project administrators (usually denise) to indicate issues that should be resolved sooner rather than later, all other things being equal, because they will reduce annoyances in the day-to-day use of the site.

##from: suggestions

Issues imported from dw_suggestions.

##from: support

##is: bug

##is: feature

##is: upkeep

##needs: docs

##effort: lower, ##effort: average, ##effort: higher

##severity: minor, ##severity: major, ##severity: critical

There are two other labels which are applied automatically: "status: claimed" when someone claims an issue (see Working on Bugs above), and "status: untriaged" which is used for issues that haven't had any of the other listed labels applied. There is also "review: requested changes" which is reserved for pull requests that need further work before they can be accepted.

All of the labels are listed on the dw-free labels page for easy searching. If you are interested in the program that applies the labels to issues automatically in response to user comments, that code is maintained in afuna's ghi-assist repository.