This guide is created to make work with labels on Github more constructive and understandable both to development and management parts of the team.
Labels are the simple and efficient way to apply additional description to your Pull Requests. Most of the project management systems provide the possibility to create fields and categories with different values to give you full control under task description. And Github uses a simple but highly flexible and efficient tag system for that.
Only few tags are provided by default: bug, duplicate, enhancement, invalid, question, won't fix. Those examples are aimed to let you understand the basics of labels usage. For example “Bug” is the type of the task and “won't fix” is its status. Labels can be named with absolutely random words and if they been chosen correctly, immediately makes clear to any developer or manager of what ticket, section, milestone is mentioned here and what's it current status.
Apart from that, labels can do a good service to project managers as a filtering system. Choosing those or other tags manager would be able to review all the tasks which are linked to them. It can be suitable to keep up with milestone velocity.
This guide is mainly aimed on being applied to Github Pull Requests. Assuming that Github provides a bunch of predefined labels all of them can be divided into four groups:
1) Milestone labels;
2) Status labels;
3) Indicator labels;
4) Management labels.
Please note this separation is conditional.
Provides the name of the Milestone of the opened Pull Request and should go first in the labels row. It's designed as an indicator and main filtering label type for managers and it's preferable to use not more then two words for its name and put it in square brackets. Please use dull colors close to background which wouldn't annoy and attract too much attention.
Examples: [OASIS], [MILESTONE_ONE]
View:
Provides current status of the opened Pull Request. Among the possible statuses may be used: Needs Review, In Review, WIP (work in progress), Done and so on. Please choose bright colors for those labels because, unlike milestones, it should attract team's attention and reflect the state of code in Pull Request.
Examples: NEEDS REVIEW, IN REVIEW, REVIEWED, NEEDS SYNC, WIP, DONE
For example:
Unlike the other groups of labels usage of indicator labels is not mandatory. Labeling Pull Request with indicator label provides additional info about state, code, actions with it etc. For example Pull Request which closes a bug may be labeled with 'Bug'.
Examples: bug, question, enhancement, do not merge
For example:
Indicates location of the Pull Request's code. For example, your pull request was merged and deployed to the staging branch and currently under review of the test team. So it should be labeled with something like 'On Staging' one. Please choose neutral tones for that kind of labels.
Examples: [on staging], [on production]
For example:
Depending on past experience I would like to present few possible situations for better understanding labels usage. Let's assume we have staging and production instances and Pull Request needs to pass few checks before been applied, merged and deployed to production.
Once opened new Pull Request and described what was done there I would put:
1) [MILESTONE],
2) NEEDS REVIEW (for code reviewer attention attraction purposes).
While checking Pull Request code reviewer switches label to 'IN REVIEW'. At the end code reviewer added few remarks and removes in-review label. After fixing developer repeats the step with 'NEEDS REVIEW' label. When Pull Request finally passed checks, it would be labeled with 'DONE'. Resulted labels list would be: (a) [MILESTONE], IN REVIEW; (b) [MILESTONE], 'NEEDS REVIEW'; (c) [MILESTONE], 'DONE'
After successful merge and deploy to staging server the test team includes to work process. While merging Pull Request to staging branch label 'On Staging' and 'IN REVIEW' should be added. Resulted list: [MILESTONE], 'DONE', 'On Staging'
After testers checked staging changes and also added few notes, Pull Request repeats the way from 3.1 to 3.3. Just before merging all tested and reviewed code to production branch label is being switched from 'On Staging' to 'On Prod'. Resulted list: [MILESTONE], 'DONE', 'On Prod'
Can you please fix the images? They are not loading. Thank you for the guide!