GitHub conventions
This page describes some common conventions and guidelines that we follow in all of our GitHub repositories within the nebari-dev
organization.
GitHub labels for issues and pull requestsâ
There are a few GitHub labels that we use to provide key metadata in our issues and pull requests.
These are added to all nebari-dev/
repositories, and share the same meaning across each of them.
Issues and pull requests are classified by having a type
label and a number of optional labels such as area
or impact
.
note
Repositories may define their own labels in addition to the ones described here to better reflect the areas and scope of the project.
Issue typeâ
REQUIRED đ
Issue type determines the kind of issue and implies what sorts of actions must be taken to close it. All issues must be assigned a type label as soon as possible. Issue types are mutually-exclusive - there may only be one issue type per issue.
There are a few issue types that are defined for all repositories, for example:
type: enhancement đ đŧ
: an incremental improvement to somethingtype: bug đ
: a problem that needs to be fixedtype: maintenance đ
: regular maintenance and upkeeptype: discussion đŦ
: discussion of general questions, ideas and so on
In addition, other repositories may use repository-specific types, with the caveat that all issues must still only have one type
label.
Issue impactâ
OPTIONAL
Issue impact is used to signal how much of an impact resolving an issue will have. The meaning of this depends on the issue type (for example, enhancement, bug).
The impact should be proportional to a combination of:
- The number of users that will be impacted by an issue's resolution,
- The extent of the impact our users will feel (for example a major change in experience versus minor improvement)
- The importance of communities or stakeholders that are impacted by the issue.
These are the impact labels for our issues:
impact: high đĨ
impact: medium đ¨
impact: low đŠ
Categorizing impactâ
Here are a few guidelines for how to categorize impact across a few major types of issues.
Features / Enhancements
impact: high
: Will be seen and commonly used by nearly all users. Has been requested by an abnormally large number of users. Is of particular importance to a key community.impact: med
: Useful to many users but not an overwhelming amount. Will be a less-obvious improvement. Most issues should be in this category.impact: low
: Useful but not a critical part of workflows. Is a niche use-case that only a few users may need.
Bugs
impact: high
: Disruptive to nearly all users, or critically disruptive to many users or key communities (for example, instances won't work at all).impact: med
: Disruptive to some users, but not in a critical way. Only noticeable under circumstances that aren't very common. Most issues should be in this category.impact: low
: Minimally disruptive or cosmetic, or only affects a few users or niche use-cases. Note thataccessibility
related issues should beimpact: high
as these are never purely cosmetic changes.
Area tagâ
OPTIONAL
Tag labels provide hints about what topics that issue is relevant to. They are highly repository-specific, optional, and non-exclusive (so issues may have many tags associated with them).
Here are some example tags:
area: documentation đ
: related to documentation in a repositoryarea: CI đˇđŊââī¸
: related to continuous integration/deploymentarea: design đ¨
: related to design items including UX/UI and graphic design
Needs labelsâ
OPTIONAL
These labels are used to denote what sort of action is needed to resolve an issue or move a pull request forward.
needs: discussion đŦ
: this issue needs to be discussed in a meeting or in a GitHub issueneeds: follow-up đĢ
: someone in the team needs to follow up on this issue or with another stakeholderneeds: review đ
: this issue needs to be reviewed by a team memberneeds: triage đĻ
: this issue needs to be triaged by a team memberneeds: investigation đ
: this issue needs to be investigated by a team member, often used when an issue was submitted without enough information or reproduction stepsneeds: changes đ§ą
: this pull request has been reviewed and changes have been requestedneeds: tests â
: tests need to be added or updated to close this pull requestneeds: documentation đ
: documentation needs to be added or updated to close this pull requestneeds: PR đŦ
: this issue needs to be worked on, usually as a pull request
Other labelsâ
A few labels exist to denote particular situations:
Close?
: to denote an issue that might need closing, either because the discussion has dried out or there are no concrete follow-up actionsDO-NOT-MERGE
: to denote a PR that should not be merged yetgood first issue
: these issues represents self-contained work that would make a good introduction to project development for a new contributorRoadmap đ
: this issue is part of the project roadmap
Pull requestsâ
Pull requests are usually associated with or linked to issues. The natural path is to start with an issue and move onto a pull request for resolution. But sometimes a new pull request is created without an associated issue. In such cases a new issue should be created for that pull request to engage people in a general discussion, not the technical review which is performed in the pull request itself.
If the PR does not need a discussion (trivial fixes, tasks, and so on), the opening of an associated issue may be skipped, but the pull request must be labeled accordingly.
We use mutually exclusive GitHub labels with the prefixstatus:
to classify PR's.
status: abandoned đ
: this pull request has not seen activity in a while (at least a month)status: stale đĨ
: a "stale" pull request is one that is no longer up to date with the main line of development, and it needs to be updated before it can be merged into the project.status: in progress đ
: this PR is currently being worked onstatus: in review đ
: this PR is currently being reviewed by the teamstatus: declined đ đģââī¸
: this PR has been reviewed and declined for mergedstatus: approved đĒđž
: this PR has been reviewed and approved for mergestatus: blocked âī¸
: this PR is blocked by another PR or issue
GitHub notifies team member when labels are changed, so it is useful to keep the status of each pull request as close as possible with the reality.
For example, if you realize that your PR needs more work after a first pass review, then change the label to status: in progress đ
.
All PR's must be tagged with a status at all times
Issue and PR templatesâ
We use Issue and PR Templates to provide helpful prompts for common issues across all of our repositories. These templates live in our .github repository and are automatically synchronized with several other repositories through a GitHub Workflow.
When you update one of the issue templates in that repository, a PR will automatically be created for the other repositories that are defined in the sync.yml file.