Difference between revisions of "Github Issues"
From Dreamwidth Notes
(→Logging bugs) |
(→Working on Bugs) |
||
| (10 intermediate revisions by 3 users not shown) | |||
| Line 6: | Line 6: | ||
[https://help.github.com/articles/signing-up-for-a-new-github-account Github's guide on signing up for a new account]. You can use a free personal plan to collaborate with Dreamwidth. | [https://help.github.com/articles/signing-up-for-a-new-github-account Github's guide on signing up for a new account]. You can use a free personal plan to collaborate with Dreamwidth. | ||
| − | === | + | ===Reporting Bugs=== |
| − | '''DO NOT''' use this process for security issues | + | <div style="padding:1em; background-color:#fee;">'''DO NOT''' use this process for security issues. Any security concerns should be reported privately to our staff -- you can email Denise and Mark. (denise@/mark@ the site's domain.)</div> |
| − | + | # Go to the dw-free repository's [https://github.com/dreamwidth/dw-free/issues Issues]. (You can also get there from the main page for the [https://github.com/dreamwidth/dw-free dw-free repository], looking on the right-hand sidebar for the "Issues" link.)<br /><br /> | |
| + | # 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.)<br /><br /> | ||
| + | # 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 "[https://github.com/dreamwidth/dw-free/issues/new New Issue]".<br /><br /> | ||
| + | # 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.<br /><br /> | ||
| + | # 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.<br /><br /> | ||
| + | # When you're done, click 'Submit new Issue'. | ||
| − | + | ===Working on Bugs=== | |
| + | # 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 [https://github.com/orgs/dreamwidth/teams/contributors 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.<br /><br /> | ||
| + | # To find an existing issue to work on, go to the dw-free repository's [https://github.com/dreamwidth/dw-free/issues 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. <br /><br /> | ||
| + | # To see all unclaimed (available) issues, click on the "Assignee" dropdown below the search field, and choose "[https://github.com/dreamwidth/dw-free/issues?q=is%3Aopen+is%3Aissue+no%3Aassignee Assigned to nobody]". You can filter with multiple constraints: for example, to see [https://github.com/dreamwidth/dw-free/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+-label%3A%22status%3A+claimed%22 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 [https://github.com/dreamwidth/dw-free/issues?q=is%3Aopen+is%3Aissue+no%3Aassignee+label%3A%22curated%3A+beginner%22 unassigned issues that have been selected as suitable for beginning coders or people new to our codebase]! The [https://github.com/dreamwidth/dw-free/labels labels page] lists all of our current tags for issues, with links to search on each. [https://github.com/dreamwidth/dw-free/milestones 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 [http://wiki.dreamwidth.net/wiki/index.php/Github_Issues#Curating_Bugs Curating Bugs] below for more about the labels we use.)<br /><br /> | ||
| + | # 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!"<br /><br /> | ||
| + | # 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.<br /><br /> | ||
| + | # 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 [https://help.github.com/articles/closing-issues-via-commit-messages/ 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, <dwuser>afuna</dwuser> wrote a monitoring service (bot) to add labels to issues in respond to comments. These are the label comments currently recognized by the system: | |
| − | + | <dt><pre>##curated: beginner</pre></dt> | |
| + | <dd>Used for "babydev bait" - relatively simple fixes appropriate for new contributors who are just getting their feet wet.</dd> | ||
| − | + | <dt><pre>##curated: mostwanted</pre></dt> | |
| + | <dd>Used by project administrators (usually <dwuser>denise</dwuser>) 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.</dd> | ||
| − | + | <dt><pre>##from: suggestions</pre></dt> | |
| + | <dd>Issues imported from <dwuser>dw_suggestions</dwuser>.</dd> | ||
| − | + | <dt><pre>##from: support</pre></dt> | |
| + | <dd>Issues generated from support requests.</dd> | ||
| − | + | <dt><pre>##is: bug</pre></dt> | |
| + | <dd>Things that are broken that need to be fixed.</dd> | ||
| − | + | <dt><pre>##is: feature</pre></dt> | |
| + | <dd>New functionality for the site, or significantly improving functionality of an existing feature.</dd> | ||
| − | + | <dt><pre>##is: upkeep</pre></dt> | |
| + | <dd>Maintenance tasks, like adding site embeds, mood themes, or new styles. Converting pages to Template Toolkit and/or Foundation is also categorized here.</dd> | ||
| − | + | <dt><pre>##needs: docs</pre></dt> | |
| + | <dd>Issues that require changes to site documentation (e.g. FAQs).</dd> | ||
| − | + | <dt><pre>##effort: lower, ##effort: average, ##effort: higher</pre></dt> | |
| + | <dd>Most issues will have one of these tags as a best guess for how much effort they will require to implement. The simplest is lower (measured in hours), followed by average (measured in days) and higher (measured in weeks). They really are our best guess up front -- sometimes we get it wrong and something labelled "effort: lower" will wind up being much more sprawling or something labelled "effort: higher" will wind up being a two second fix once you find the root cause!</dd> | ||
| − | + | <dt><pre>##severity: minor, ##severity: major, ##severity: critical</pre></dt> | |
| + | <dd>Most issues will have one of these tags as a best guess for how much impact the issue has on the day-to-day functioning of the site. Minor is by far the most common, meaning the site is still functioning just fine for most users and the proposed change will have little impact; major is for issues that are "breaking the build" in development or preventing some people from using the site, or for significant new features; and critical means DROP EVERYTHING THE SITE IS ON FIRE. (Probably. We don't actually use this one much, unsurprisingly.)</dd> | ||
| + | <hr /> | ||
| + | There are two other labels which are applied automatically: "status: claimed" when someone claims an issue (see [http://wiki.dreamwidth.net/wiki/index.php/Github_Issues#Working_on_Bugs 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 [https://github.com/dreamwidth/dw-free/labels 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 <dwuser>afuna</dwuser>'s [https://github.com/afuna/ghi-assist ghi-assist] repository. | |
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
[[Category: Development]] | [[Category: Development]] | ||
[[Category: Git]] | [[Category: Git]] | ||
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 ![[info]](http://wiki.dreamwidth.net/wiki/extensions/LJ/images//dw/user.png){kind=small}
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
DO NOT use this process for security issues. Any security concerns should be reported privately to our staff -- you can email Denise and Mark. (denise@/mark@ the site's domain.)
- 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.)
- 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.)
- 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".
- 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.
- 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.
- When you're done, click 'Submit new Issue'.
Working on Bugs
- 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.
- 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.
- 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.)
- 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!"
- 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.
- 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
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
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.
