This page describes some common conventions and guidelines that we follow in all of our GitHub repositories within the
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
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 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 something
type: bug 🐛: a problem that needs to be fixed
type: maintenance 🛠: regular maintenance and upkeep
type: 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
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 🟩
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.
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 that
accessibilityrelated issues should be
impact: highas these are never purely cosmetic changes.
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 repository
area: CI 👷🏽♀️: related to continuous integration/deployment
area: design 🎨: related to design items including UX/UI and graphic design
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 issue
needs: follow-up 📫: someone in the team needs to follow up on this issue or with another stakeholder
needs: review 👀: this issue needs to be reviewed by a team member
needs: triage 🚦: this issue needs to be triaged by a team member
needs: investigation 🔍: this issue needs to be investigated by a team member, often used when an issue was submitted without enough information or reproduction steps
needs: changes 🧱: this pull request has been reviewed and changes have been requested
needs: tests ✅: tests need to be added or updated to close this pull request
needs: documentation 📖: documentation needs to be added or updated to close this pull request
needs: PR 📬: this issue needs to be worked on, usually as a pull request
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 actions
DO-NOT-MERGE: to denote a PR that should not be merged yet
good first issue: these issues represents self-contained work that would make a good introduction to project development for a new contributor
Roadmap 🚀: this issue is part of the project roadmap
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 prefix
status: 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 on
status: in review 👀: this PR is currently being reviewed by the team
status: declined 🙅🏻♀️: this PR has been reviewed and declined for merged
status: approved 💪🏾: this PR has been reviewed and approved for merge
status: 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.