-
Notifications
You must be signed in to change notification settings - Fork 52
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Copy and update inital community docs from Nebari
- Loading branch information
1 parent
432eaa1
commit 5b527c5
Showing
16 changed files
with
588 additions
and
39 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -2,4 +2,4 @@ | |
description: Contribute to conda-store | ||
--- | ||
|
||
# Contribute to conda-store | ||
# Contribute to conda-store's codebase |
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
144 changes: 144 additions & 0 deletions
144
docusaurus-docs/community/maintenance/github-conventions.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,144 @@ | ||
--- | ||
description: GitHub conventions for the conda-store issue and pull request trackers | ||
--- | ||
|
||
# GitHub conventions | ||
|
||
This page describes some common conventions and guidelines that we follow in all the conda-store GitHub repositories. | ||
|
||
## 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`](#issue-type) label and a number of optional labels such as [`area`](#area-tag) or [`impact`](#issue-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 :pushpin:** | ||
|
||
**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 `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 that `accessibility` related issues should be `impact: 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 repository | ||
- `area: CI 👷🏽♀️`: related to continuous integration/deployment | ||
- `area: 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 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 | ||
|
||
### 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 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 | ||
|
||
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](https://github.com/nebari-dev/.github) repository and are automatically synchronized with several other repositories through a [GitHub Workflow](https://github.com/nebari-dev/.github/blob/main/.github/workflows/sync-issue-templates.yaml). | ||
|
||
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](https://github.com/nebari-dev/.github/blob/main/.github/sync.yml). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,11 @@ | ||
--- | ||
sidebar_position: 3 | ||
description: Guidelines and resources for conda-store maintenance efforts | ||
--- | ||
|
||
# Maintenance guidelines | ||
|
||
import DocCardList from '@theme/DocCardList'; | ||
import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; | ||
|
||
<DocCardList items={useCurrentSidebarCategory().items}/> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
--- | ||
description: Release process for all conda-store packages | ||
--- | ||
|
||
# Release process |
126 changes: 126 additions & 0 deletions
126
docusaurus-docs/community/maintenance/reviewer-guidelines.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,126 @@ | ||
--- | ||
description: Guidelines and tips for reviewing contributions to Nebari | ||
--- | ||
|
||
# Reviewer guidelines | ||
|
||
## Who can be a reviewer? | ||
|
||
Reviewing open pull requests (PRs) or other contributions helps move the project forward. | ||
We encourage people outside the project to get involved as well; it’s a great way to get familiar with the project and | ||
its development workflow. | ||
|
||
## Communication guidelines | ||
|
||
- Every PR, good or bad, is an act of generosity. Opening with a positive comment will help the author feel rewarded, | ||
and your subsequent remarks may be heard more openly. You may feel good also. | ||
- Begin if possible with the large issues, so the author knows they’ve been understood. | ||
Resist the temptation to immediately go line by line, or to open with small pervasive issues. | ||
- You are the face of the project, and the Nebari project aims to be: open, empathetic, welcoming, friendly and patient. | ||
[Be kind to contributors](https://youtu.be/tzFWz5fiVKU?t=49m30s). | ||
- Do not let perfect be the enemy of the good, particularly for documentation. If you find yourself making many small suggestions, | ||
or being too nitpicky on style or grammar, consider merging the current PR when all important concerns are addressed. | ||
Then, either push a commit directly (if you are a maintainer) or open a follow-up PR yourself. | ||
- Do not rush, take the time to make your comments clear and justify your suggestions. | ||
- If you review a pull request from a "first-time contributor" (you will see a label on their pull request), be a little more patient with them and include additional context to your suggestions. | ||
|
||
:::tip | ||
If you need help writing replies in reviews, check out our [standard replies for reviewing][saved-replies]. | ||
::: | ||
|
||
## Reviewer checklist | ||
|
||
Here are a few important aspects that need to be covered in any review. | ||
Note this is not an exhaustive, nor strictly list of items to cover on each review, use your best judgement. | ||
|
||
- Do we want this in the project? Will the cost of maintaining it outweigh the benefits? | ||
Is this solving a niche use case or would it benefit the broader community? Should this contribution be made to an upstream project instead? | ||
- Pull requests need triaging too - if you have the correct permissions, | ||
add the relevant labels as detailed in our [GitHub conventions docs][github-conventions]. | ||
- Should comments be added, or rather removed as unhelpful or extraneous? | ||
- Do the documentation and code style adhere to our style guides? | ||
- Does this contribution require changes or additions to the documentation? Have these changes been made? If not, | ||
add the `needs: docs 📖` label to the PR. | ||
- Do the tests pass in the continuous integration build? If appropriate, help the contributor understand why tests failed. | ||
Add the `needs: changes 🧱` label if the PR needs to be updated. | ||
- For code changes, at least one maintainer (someone with commit rights) should review and approve a pull request. | ||
If you are the first to review a PR and approve of the changes use the GitHub approve review tool to mark it as such. | ||
If a PR is straightforward, for example it’s a clearly correct bug fix, it can be merged straight away. | ||
If it’s more complex or introduces breaking changes, please leave it open for at least a couple of days, so other maintainers get a chance to review. | ||
You can also consider mentioning or requesting a review from specific maintainers who are familiar with relevant parts of the codebase. | ||
- If you are a subsequent reviewer on an already approved PR, please use the same review method as for a new PR | ||
(focus on the larger issues, resist the temptation to add only a few nitpicks). | ||
If you have commit rights and think no more review is needed, merge the PR. | ||
- If the PR is missing tests or the tests have not been updated let the contributor know and add the `needs: tests ✅` label. | ||
- If the PR fixes an issue, the PR must mention that issue in the PR body for example `gh-xyz`. | ||
|
||
### For maintainers | ||
|
||
Only maintainers can merge pull requests. Please follow these guidelines: | ||
|
||
- Make sure all automated CI tests pass before merging a PR, and that the documentation builds without any errors. | ||
- If the contribution is made to the `nebari-dev/nebari` repository, then you'll need to trigger the Kubernetes tests | ||
by commenting `/bot run tests` on the PR. | ||
- If the contribution is made to the `nebari-dev/nebari-docs` repository, then make sure to check the Netlify build and preview. | ||
- In case of merge conflicts, ask the PR submitter to rebase on `develop`. | ||
- Squashing commits or cleaning up commit messages of a PR that you consider too messy is OK. | ||
Remember to retain the original author’s name when doing this. | ||
- When you want to reject a PR: if it’s very straightforward, you can close it and explain why. If it’s not, | ||
then it’s a good idea to first explain why you think the PR is not suitable for inclusion in Nebari and then let a second committer comment or close. | ||
- Maintainers are encouraged to finalize PRs when only small changes are necessary before merging | ||
(acceptable changes are fixing code style or grammatical errors). If a PR becomes inactive, maintainers may make larger changes. | ||
Remember, a PR is a collaboration between a contributor and a reviewer/s, sometimes a direct push is the best way to finish it. | ||
- You should typically not self-merge your own pull requests. Exceptions include things like small changes to fix CI | ||
(for example pinning a package version). | ||
- You should not merge pull requests that have an active discussion, or pull requests that has been proposed for rejection | ||
by another maintainer. | ||
|
||
## GitHub workflow | ||
|
||
When reviewing pull requests, please use workflow tracking features on GitHub as appropriate. | ||
|
||
1. After you have finished reviewing, if you want to ask for the submitter to make changes, | ||
change your review status to “Changes requested.” This can be done on GitHub, PR page > Files changed tab, Review changes (button on the top right). | ||
Add the `needs: changes 🧱` label to the PR (or other relevant labels like `needs: tests` or `needs: docs`). | ||
2. If you’re happy about the current status, mark the pull request as Approved (same way as Changes requested) and add the `status: approved 💪🏾` label. | ||
3. **Alternatively (for maintainers):** merge the pull request, if you think it is ready to be merged. | ||
All the pull requests are **squashed merged** retaining the original author’s name. | ||
|
||
## Asking questions | ||
|
||
You are encouraged to ask questions and seek an understanding of what the PR is doing; however, your question might be answered further into the review. | ||
You can stage your questions, and before you submit your review, revisit your own comments to see if they're still relevant or update them after gaining further context. | ||
|
||
Often a question may turn into a request for further comments or changes to explain what is happening at that specific point. | ||
|
||
In your questions, try and be empathetic when phrasing. Instead of: "Why did you do this?" | ||
|
||
try: **"Am I understanding this correctly? Can you explain why...?"** | ||
|
||
Remember a review is a discussion, often with multiple parties -- be reasonable. | ||
Try to focus and summarize in ways which constructively move the conversation forward instead of retreading ground. | ||
|
||
## Asking for changes | ||
|
||
It's okay to ask for changes to be made on a PR. | ||
In your comments, you should be clear on what is a 'nit' or small thing to be improved and a required change needed to accept the PR. | ||
|
||
Be clear and state upfront architectural or larger changes. These should be resolved first before addressing any further nits. | ||
Also, make sure to add the `needs: changes 🧱` label to the PR. | ||
|
||
It's also okay to say "No" to a PR. As a community, we want to respect people's time and efforts, | ||
but sometimes things don't make sense to accept. | ||
As reviewers, you are the stewards of the code-base and sometimes that means pushing back on potential changes. | ||
|
||
## Acknowledgements | ||
|
||
Our reviewer guidelines were inspired and adapted from: | ||
|
||
- NumPy's [reviewer guidelines](https://numpy.org/devdocs/dev/reviewer_guidelines.html) | ||
- Kubernetes' [reviewer guidelines](https://github.com/kubernetes/community/blob/master/contributors/guide/review-guidelines.md) | ||
- scikit-learn [reviewer guidelines](https://scikit-learn.org/stable/developers/contributing.html#code-review-guidelines) | ||
|
||
<!-- Internal links --> | ||
|
||
[saved-replies]: ./saved-replies.md | ||
[github-conventions]: community/maintainers/github-conventions.md |
Oops, something went wrong.