From 01ef8962f48bbfa21197301619511aa0857c8e76 Mon Sep 17 00:00:00 2001 From: Pavithra Eswaramoorthy Date: Mon, 16 Oct 2023 22:06:23 +0530 Subject: [PATCH] [DOC] Add Community documentation (#579) Co-authored-by: Tania Allard --- .../community/contribute/contribute-code.md | 7 + .../community/contribute/contribute-docs.md | 4 +- .../contribute/contribute-extension.md | 5 - .../community/contribute/contribute-ui.md | 5 - docusaurus-docs/community/contribute/index.md | 5 +- .../community/contribute/issues.md | 71 +++++++++ .../{contribute-core.md => testing.md} | 4 +- .../community/contribute/triage.md | 5 - .../community/github-conventions.md | 5 - docusaurus-docs/community/governance.md | 5 - docusaurus-docs/community/introduction.md | 73 ++++++++- .../maintenance/github-conventions.md | 141 ++++++++++++++++++ .../community/maintenance/index.md | 11 ++ .../community/{ => maintenance}/release.md | 0 .../maintenance/reviewer-guidelines.md | 116 ++++++++++++++ .../community/maintenance/saved-replies.md | 123 +++++++++++++++ .../community/maintenance/triage.md | 117 +++++++++++++++ docusaurus-docs/community/support.md | 5 - docusaurus-docs/conda-store/introduction.md | 15 +- docusaurus-docs/docusaurus.config.js | 4 +- docusaurus-docs/src/pages/index.js | 4 +- 21 files changed, 677 insertions(+), 48 deletions(-) create mode 100644 docusaurus-docs/community/contribute/contribute-code.md delete mode 100644 docusaurus-docs/community/contribute/contribute-extension.md delete mode 100644 docusaurus-docs/community/contribute/contribute-ui.md create mode 100644 docusaurus-docs/community/contribute/issues.md rename docusaurus-docs/community/contribute/{contribute-core.md => testing.md} (60%) delete mode 100644 docusaurus-docs/community/contribute/triage.md delete mode 100644 docusaurus-docs/community/github-conventions.md delete mode 100644 docusaurus-docs/community/governance.md create mode 100644 docusaurus-docs/community/maintenance/github-conventions.md create mode 100644 docusaurus-docs/community/maintenance/index.md rename docusaurus-docs/community/{ => maintenance}/release.md (100%) create mode 100644 docusaurus-docs/community/maintenance/reviewer-guidelines.md create mode 100644 docusaurus-docs/community/maintenance/saved-replies.md create mode 100644 docusaurus-docs/community/maintenance/triage.md delete mode 100644 docusaurus-docs/community/support.md diff --git a/docusaurus-docs/community/contribute/contribute-code.md b/docusaurus-docs/community/contribute/contribute-code.md new file mode 100644 index 000000000..c8376d458 --- /dev/null +++ b/docusaurus-docs/community/contribute/contribute-code.md @@ -0,0 +1,7 @@ +--- +description: Contribute to conda-store's codebase +--- + +# Contribute code + + diff --git a/docusaurus-docs/community/contribute/contribute-docs.md b/docusaurus-docs/community/contribute/contribute-docs.md index 78729fd6f..3c829020a 100644 --- a/docusaurus-docs/community/contribute/contribute-docs.md +++ b/docusaurus-docs/community/contribute/contribute-docs.md @@ -2,4 +2,6 @@ description: Contribute to conda-store's documentation --- -# Contribute to conda-store's documentation +# Contribute documentation + + diff --git a/docusaurus-docs/community/contribute/contribute-extension.md b/docusaurus-docs/community/contribute/contribute-extension.md deleted file mode 100644 index 8f633df35..000000000 --- a/docusaurus-docs/community/contribute/contribute-extension.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -description: Contribute to conda-store JupyterLab extension ---- - -# Contribute to conda-store JupyterLab extension diff --git a/docusaurus-docs/community/contribute/contribute-ui.md b/docusaurus-docs/community/contribute/contribute-ui.md deleted file mode 100644 index b024fc438..000000000 --- a/docusaurus-docs/community/contribute/contribute-ui.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -description: Contribute to conda-store UI ---- - -# Contribute to conda-store UI diff --git a/docusaurus-docs/community/contribute/index.md b/docusaurus-docs/community/contribute/index.md index 676e1641a..503518a5b 100644 --- a/docusaurus-docs/community/contribute/index.md +++ b/docusaurus-docs/community/contribute/index.md @@ -1,8 +1,9 @@ --- -description: Contribute +sidebar_position: 2 +description: Guidelines for conda-store contributors --- -# Contribute +# Contribution guidelines import DocCardList from '@theme/DocCardList'; import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; diff --git a/docusaurus-docs/community/contribute/issues.md b/docusaurus-docs/community/contribute/issues.md new file mode 100644 index 000000000..3b9d5c577 --- /dev/null +++ b/docusaurus-docs/community/contribute/issues.md @@ -0,0 +1,71 @@ +--- +description: Best practices for opening issues +--- + +# Create and improve issues + +## Submit bug report or feature request + +The conda-store issue trackers are the preferred channel for bug reports, documentation requests, and submitting pull requests. + +To resolve your issue, please select the appropriate category and follow the prompts to provide as much information as +possible: + +- **Bug Report:** When something is not working as expected and documented +- **Feature request:** Request new enhancements to conda-store +- **Usage question:** Questions about how to use conda-store +- **General issue:** Anything that doesn't fit the above categories + +## Best practices + +When opening an issue, use a **descriptive title** and include all relevant details about your bug and environment (operating system, Python version, conda-store version, etc.). Our issue template helps you remember the most important details to include. + +A few more tips: + +- **Describing your issue**: Try to provide as many details as possible. What exactly goes wrong? How is it failing? + Is there an error? "XY doesn't work" usually isn't that helpful for tracking down problems. + Provide clear instructions for how to reproduce your issue. + Always remember to include the code you ran and if possible, + extract only the relevant parts and don't dump your entire script. + You can also add screenshots and recordings of the issue. + This is essential for the development team to triage, prioritize, and resolve your issue. + +- **Getting info about your conda-store installation and environment**: You can use the command line interface to print details and even format them as Markdown to copy-paste into GitHub issues. + +- **Sharing long blocks of code or logs**: If you need to include long code, logs or trace backs, you can wrap them in `
` and `
`. + This collapses the content, so it only becomes visible on click, making the issue easier to read and follow. + +:::tip +See this page for an overview of the [system we use to tag our issues and pull requests][github-conventions]. +::: + +## Suggested workflow + +If an issue is affecting you, start at the top of this list and complete as many tasks on the list as you can: + +1. Check the issue tracker, if there is an open issue for this same problem, add a reaction or more details to the issue + to indicate that it’s affecting you (tip: make sure to also check the open pull requests for ongoing work). +2. If there is an open issue, and you can add more detail, write a comment describing how the problem is affecting you (tip: learn to improve issues in the next section), + OR if you can, write up a work-around or improvement for the issue. +3. If there is not an issue, write the most complete description of what’s happening including reproduction steps. +4. [Optional] - Offer to help fix the issue (and it is totally expected that you ask for help; open-source maintainers want to help contributors). +5. [Optional] - If you decide to help to fix the issue, deliver a well-crafted, tested PR. + +## Improve existing issues + +Improving issues increases their chances of being successfully resolved. A third party can give useful feedback or even add comments on the issue. + +The following actions are typically useful: + +- Add missing elements that are blocking progress such as code samples to reproduce the problem. +- Suggest better use of code formatting. +- Suggest reformulating the title and description to make them more explicit about the problem to be solved. +- Link to related issues or discussions while briefly describing how they are related, for instance “See also #xyz for a similar attempt at this” or “See also #xyz where the same thing happened in another cloud provider" provides context and helps the discussion. +- Summarize long discussions on issues to help new and existing contributors quickly understand the background, current status, and course of action for the issue. + +You can further [contribute to triaging efforts with these guidelines][triage]. + + + +[github-conventions]: /community/maintenance/github-conventions +[triage]: /community/maintenance/triage diff --git a/docusaurus-docs/community/contribute/contribute-core.md b/docusaurus-docs/community/contribute/testing.md similarity index 60% rename from docusaurus-docs/community/contribute/contribute-core.md rename to docusaurus-docs/community/contribute/testing.md index e8cc03fb2..745698f62 100644 --- a/docusaurus-docs/community/contribute/contribute-core.md +++ b/docusaurus-docs/community/contribute/testing.md @@ -2,4 +2,6 @@ description: Contribute to conda-store --- -# Contribute to conda-store +# Run test suite + + diff --git a/docusaurus-docs/community/contribute/triage.md b/docusaurus-docs/community/contribute/triage.md deleted file mode 100644 index f23b0acb3..000000000 --- a/docusaurus-docs/community/contribute/triage.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -description: Triage ---- - -# Triage diff --git a/docusaurus-docs/community/github-conventions.md b/docusaurus-docs/community/github-conventions.md deleted file mode 100644 index aa6d2cd9c..000000000 --- a/docusaurus-docs/community/github-conventions.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -description: GitHub conventions ---- - -# GitHub conventions diff --git a/docusaurus-docs/community/governance.md b/docusaurus-docs/community/governance.md deleted file mode 100644 index 2c303e4c5..000000000 --- a/docusaurus-docs/community/governance.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -description: Governance ---- - -# Governance diff --git a/docusaurus-docs/community/introduction.md b/docusaurus-docs/community/introduction.md index 6ce8d0bc5..80eb8ff85 100644 --- a/docusaurus-docs/community/introduction.md +++ b/docusaurus-docs/community/introduction.md @@ -4,4 +4,75 @@ title: Introduction description: Community documentation --- -# conda-store community +# Welcome to conda-store! + +conda-store is a set of open source tools for managing data science environments in collaborative teams. It provides flexible-yet-reproducible environments and a user-friendly graphical interface, while enforcing best practices throughout the environment's life cycle. + +## Projects + +conda-store consists of three projects which are developed on separate GitHub repositories. The each have separate spaces on our documentation site as well: + +- [conda-store][conda-store-docs]: core library that provides all the key features through a REST API and CLI +- [conda-store-ui][conda-store-ui-docs]: web application (frontend) for accessing all the conda-store features +- [jupyterlab-conda-store][jupyterlab-conda-store-docs]: extension to access conda-store-ui within JupyterLab + +:::note +The term "conda-store" is heavily overloaded, it can refer to the overall set of projects, the core repository, or the package based on context. +If the meaning is unclear in a discussion, don't hesitate to ask the people involved to clarify. +::: + +## Code of Conduct + +The conda-store development team pledges to create a welcoming, supportive, and harassment-free space for everyone. All conda-store spaces, including GitHub conversations and video meetings, are covered by the [conda organization code of conduct](https://github.com/conda-incubator/governance/blob/main/CODE_OF_CONDUCT.md). + +## Governance + +As a [federated project](https://github.com/conda-incubator/governance/tree/main#federated-projects) under the [conda-incubator organization](https://github.com/conda-incubator), conda-store follows the [conda-incubator governance](https://github.com/conda-incubator/governance/tree/main#conda--conda-incubator-governance). The [conda-store development team (documented through GitHub Teams)](https://github.com/orgs/conda-incubator/teams) makes all project decisions using a [consent-based approach](https://www.sociocracyforall.org/consent-decision-making/) on the issue tracker or in team meetings. + +## Support + +conda-store's issue trackers are the best way to reach the conda-store development team. If you have any usage or contribution questions, open an issue on the corresponding repository following the [issue creation guidelines][issues]: + +* [conda-store](https://github.com/conda-incubator/conda-store/issues/new/choose) +* [conda-store-ui](https://github.com/conda-incubator/conda-store-ui/issues/new/choose) +* [jupyterlab-conda-store](https://github.com/conda-incubator/jupyterlab-conda-store/issues/new/choose) + +If you are unsure about the repository, open your issues against the `conda-store`` repository and the development team will move it to the relevant space. + +## Contribute + +There are many ways in which you can contribute to conda-store (they're all important, so we list them in alphabetical order): + +* [Code maintenance and development →][contribute-code] +* Community coordination and contributor experience +* Content translation and internationalization +* DevOps +* Fundraising +* Marketing +* Project management +* [Report bugs and submit feature requests →][issues] +* [Review pull requests →][reviewer-guidelines] +* [Triage issues and pull requests →][triage] +* Website design and development +* [Writing technical documentation →][contribute-docs] +* UI/UX + + + + + +## Acknowledgements + +conda-store's community documentation is inspired by the [Nebari community documentation](https://www.nebari.dev/docs/community). + + + + +[contribute-code]: /community/contribute/contribute-code +[contribute-docs]: /community/contribute/contribute-docs +[triage]: /community/maintenance/triage +[issues]: /community/contribute/issues +[reviewer-guidelines]: /community/maintenance/reviewer-guidelines +[conda-store-docs]: /conda-store/introduction +[conda-store-ui-docs]: /conda-store-ui/introduction +[jupyterlab-conda-store-docs]: /jupyterlab-conda-store/introduction diff --git a/docusaurus-docs/community/maintenance/github-conventions.md b/docusaurus-docs/community/maintenance/github-conventions.md new file mode 100644 index 000000000..324553698 --- /dev/null +++ b/docusaurus-docs/community/maintenance/github-conventions.md @@ -0,0 +1,141 @@ +--- +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 conda-store 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. diff --git a/docusaurus-docs/community/maintenance/index.md b/docusaurus-docs/community/maintenance/index.md new file mode 100644 index 000000000..d23828f5a --- /dev/null +++ b/docusaurus-docs/community/maintenance/index.md @@ -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'; + + diff --git a/docusaurus-docs/community/release.md b/docusaurus-docs/community/maintenance/release.md similarity index 100% rename from docusaurus-docs/community/release.md rename to docusaurus-docs/community/maintenance/release.md diff --git a/docusaurus-docs/community/maintenance/reviewer-guidelines.md b/docusaurus-docs/community/maintenance/reviewer-guidelines.md new file mode 100644 index 000000000..4c2fed3cd --- /dev/null +++ b/docusaurus-docs/community/maintenance/reviewer-guidelines.md @@ -0,0 +1,116 @@ +--- +description: Guidelines and tips for reviewing contributions to conda-store +--- + +# 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 conda-store 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. +- In case of merge conflicts, ask the PR submitter to rebase on `main`. +- 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 first to explain why you think the PR is not suitable for inclusion in conda-store 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. + + + + +[saved-replies]: /community/maintenance/saved-replies.md +[github-conventions]: /community/maintenance/github-conventions.md diff --git a/docusaurus-docs/community/maintenance/saved-replies.md b/docusaurus-docs/community/maintenance/saved-replies.md new file mode 100644 index 000000000..8d702daf8 --- /dev/null +++ b/docusaurus-docs/community/maintenance/saved-replies.md @@ -0,0 +1,123 @@ +--- +description: Standard replies for interacting with contributors +--- + +# Saved replies + +## Standard replies + +It may be helpful to store some of these in [GitHub’s saved replies](https://github.com/settings/replies/) for faster access. + +### Issue triaging + +- **Self-contained example for bug** + + _action: add `needs: investigation 🔍` label_ + + ```md + Thanks for reporting this and helping make conda-store better! + + Please provide a [self-contained example code](https://stackoverflow.com/help/mcve), including imports and data (if possible), + so that other contributors can run it and reproduce your issue. + Ideally your example code should be minimal. + ``` + +- **Duplicate issue** + + _action: add `type: duplicate 👯‍♀️` label and link to duplicate issue_ + + ```md + Thanks for taking the time to contribute! + + We noticed that this is a duplicate of [Issue URL]. You may want to subscribe there for updates. + + Because we treat our issues list as the project team's backlog, we close duplicates to focus our work and not have to touch the same chunk of code for the same reason multiple times. This is also why we may mark something as duplicate that isn't an exact duplicate but is closely related. + ``` + +- **No response: closing issue** + + _action: add `status: abandoned 🗑` label and close the issue_ + + ```md + Thanks for taking the time to open an issue! + + Unfortunately, we haven't heard back from you in a while, so we're going to close this issue. + With only the information that is currently in the issue, we don't have enough information to take action. I'm going to close this but don't hesitate to reach out if you have or find the answers we need, we'll be happy to reopen the issue. + ``` + +- **You are welcome to update the docs** + + ```md + Thanks for taking some time to make our documentation better! + + Please feel free to offer a pull request updating the documentation if you feel it could be improved. + You can find our contribution guidelines in the [conda-store documentation](https://conda.store) + ``` + +### Better comments or issues + +- **Linking to code** + + ```md + For clarity's sake, you can link to code [as shown in this GitHub documentation page](https://help.github.com/articles/creating-a-permanent-link-to-a-code-snippet/). + ``` + +- **Linking to comments** + + ```md + Please use links to comments, which make it a lot easier to see what you are referring to, rather than linking to the issue. + See [this StackOverflow question](https://stackoverflow.com/questions/25163598/how-do-i-reference-a-specific-issue-comment-on-github) for more details. + ``` + +- **Code blocks** + + ```md + Readability can be greatly improved if you [format](https://help.github.com/articles/creating-and-highlighting-code-blocks/) + your code snippets and complete error messages appropriately. + You can edit your issue descriptions and comments at any time to improve readability. + This helps maintainers a lot. Thanks! + ``` + +### Contribution reviews + +- **PR-WIP: What is needed before merge?** + + ```md + Please clarify (perhaps as a TODO list in the PR description) what work you believe still needs to be done before it can be reviewed for merge. + When it is ready, please remove the WIP from the title and request a review from a maintainer. + ``` + +- **PR: Needs tests** + + _action_: add `needs: tests ✅` label + + ```md + Thanks for your submission! + + We require automated tests for all pull requests that include new or changed code. We do this so that we can ensure that we don't accidentally break your shiny new code the next time we or some other contributor submits a change. If you need help writing automated tests, check out {{the community forum and/or documentation}}. There are a bunch of helpful community members that should be willing to point you in the right direction. + ``` + +- **Fix tests** + + _action_: add `needs: changes 🧱` label + + ```md + We notice that the automated tests are failing on this pull request. In our investigation it appears that the failing tests are caused by your changes. + In order for this pull request to be accepted, the tests will have to be fixeed. + ``` + +### Code of conduct + +:::note +The following replies should only be used by [conda-store development team members](https://github.com/orgs/conda-incubator/teams/conda-store). +::: + +- **First warning** + + ```md + [[at-mention]] your comment was [[minimized|deleted]] as a violation of the [conda organization Code of Conduct](https://github.com/conda-incubator/governance/blob/main/CODE_OF_CONDUCT.md). You may consider this an official warning. + + Please do not interact with the project for 24 hours. + After that, please look through your open issues and edit them to ensure they're entirely on-topic, + and we can continue the discussion here about the best way to go forward. + ``` diff --git a/docusaurus-docs/community/maintenance/triage.md b/docusaurus-docs/community/maintenance/triage.md new file mode 100644 index 000000000..2502b40a5 --- /dev/null +++ b/docusaurus-docs/community/maintenance/triage.md @@ -0,0 +1,117 @@ +--- +sidebar_position: 1 +description: Guidelines for triaging the conda-store issue trackers +--- + +# Triage guidelines + +Issue triage is a process by which conda-store maintainers and contributors understand and review new GitHub issues and pull requests, and organize them to be actioned. +Triaging involves categorizing issues and pull requests based on factors such as priority, area of ownership of the issue (tags), and the issue kind (bug, feature, and so on). + +We aim to triage new issues or pull requests within a week. +Triage can happen asynchronously and continuously, or in regularly scheduled meetings. + +## Why is triaging beneficial? + +Projects that triage regularly say it offers a number of benefits, such as: + +- Speeding up issue management +- Keeping contributors engaged by shortening response times +- Preventing work from lingering endlessly +- Replacing niche requests and one-offs with a neutral process that acts like a boundary +- Greater transparency, interesting discussions, and more collaborative, informed decision-making +- Building prioritization, negotiation and decision-making skills, which are critical to most tech roles +- Reinforcement of the project's community and culture + +People who enjoy product management and iterating on processes tend to enjoy triaging because it empowers their project to maintain a steady, +continuous flow of work that is assessed and prioritized based on feedback, impact, and value. + +## Triaging workflow + +### Step 1: Review newly created issues + +The first step in a triaging workflow is to review the newly created open issues in the repository. +An efficient way to do this is by using the `is:issue is:open sort:created-dec` query in the repository's issue search, +which will show the most recently created issues first (see an example of this in the [conda-store issue tracker](https://github.com/conda-incubator/conda-store/issues?q=is%3Aissue+is%3Aopen+sort%3Acreated-dec)). + +Other useful queries include: + +| Query | Example search | What it sorts | +| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | +| `is:issue is:open sort:created-dec` | [new-issues conda-store](https://github.com/conda-incubator/conda-store/issues?q=is%3Aopen+is%3Aissue) | Newest incoming issues | +| `is:issue is:open sort:comments-desc` | [comments-descending conda-store](https://github.com/conda-incubator/conda-store/issues?q=is%3Aissue+is%3Aopen+sort%3Acomments-desc) | Busiest issues, sorted by # of comments | +| `is:issue is:open sort:created-asc no:label` | [created-ascending conda-store](https://github.com/conda-incubator/conda-store/issues?q=is%3Aissue+is%3Aopen+sort%3Acreated-asc+no%3Alabel) | Untriaged issues by age | + +You can also use the [conda-store project board](https://github.com/orgs/conda-incubator/projects/8) to keep track of issues that [need triage](https://github.com/orgs/conda-incubator/projects/8/views/4) and [follow-up](https://github.com/orgs/conda-incubator/projects/8/views/9). + +### Step 2: Triage issues + +1. **First things first: thank the reporter for opening an issue.** + The issue tracker is many people’s first interaction with the conda-store project, + beyond using the project itself. As such, we want it to be a welcoming, pleasant experience for everyone. + +2. Assess the issue and label, assign, or close accordingly. + 1. Depending on your permissions, either close or comment on any issues that are identified as support requests, duplicates, or not-reproducible bugs, or that lack enough information from the reporter (see sections below). + 2. Make sure that the title accurately reflects the issue. If you have the necessary permissions edit it yourself if it's not clear. + 3. Add the relevant labels. + Detailed rationale on our labelling system can be found in the [GitHub conventions section][github-conventions] of our documentation. + +:::tip +Assign one and only one `type:` label to the issue and as many `area:` labels as are relevant. + +Feel free to [use our saved replies][saved-replies] to help you with triaging. +::: + +#### Abandoned or wrongly placed issues + +If an issue is abandoned or in the wrong place, either close, move it, or comment on it. + +#### Needs more information + +The `needs: investigation 🔎` or `needs: more information 📝` label indicates an issue needs more information in order for work to continue; comment on or close it. +This can be steps to reproduce the bug, details on the environment, or any other information that would help the issue move forward. + +#### Bugs + +First, validate if the problem is a bug by trying to reproduce it. + +If you can reproduce it: + +- Define its impact and area (see our [GitHub conventions section][github-conventions] for more details). +- Search for duplicates to see if the issue has been reported already. If a duplicate is found, let the issue reporter know, + reference the original issue, add the `duplicate 👯‍♀️` label, and close the duplicate. + +If you can't reproduce it: + +- Contact the issue reporter with your findings +- Close the issue if both the parties agree that it could not be reproduced + +If you need more information to further work on the issue: + +- Let the reporter know it by adding an issue comment, and label the issue with `needs: investigation 🔎`. + +In all cases, if you do not get a response within 20 days, close the issue with an appropriate comment. +If you have permission to close someone else's issue, add an informative message, optionally `assign` the issue to yourself, then `close` it. +If you do not, please leave a comment describing your findings and ask for the issue to be closed. + +#### Self-Assigning + +If you think you can fix the issue, assign it to yourself. If you cannot self-assign for permissions-related reasons, +leave a comment that you'd like to claim it and begin working on a PR. + +When an issue already has an assignee, **do not** assign it to yourself or create a PR without talking to the existing assignee first. +Creating a PR when someone else is already working on an issue is not a good practice and is discouraged. + +## Further notes + +Opening new issues and leaving comments on other people's issues is possible for all contributors. +However, permission to assign specific labels (such as `type: enhancement 💅🏼`), change milestones, +or close other contributors' issues is only granted to the author of an issue, assignees, and organization members. + +We have multiple [saved replies][saved-replies] that can be used to help triage issues and while conducting contributions reviews. + + + + +[saved-replies]: /community/maintenance/saved-replies +[github-conventions]: /community/maintenance/github-conventions.md diff --git a/docusaurus-docs/community/support.md b/docusaurus-docs/community/support.md deleted file mode 100644 index d4565116b..000000000 --- a/docusaurus-docs/community/support.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -description: Support ---- - -# Support diff --git a/docusaurus-docs/conda-store/introduction.md b/docusaurus-docs/conda-store/introduction.md index ab690d571..90361541c 100644 --- a/docusaurus-docs/conda-store/introduction.md +++ b/docusaurus-docs/conda-store/introduction.md @@ -1,17 +1,14 @@ --- sidebar_position: 1 title: Introduction -description: Introduction to documentation. +description: Introduction to conda-store documentation --- -# Welcome to conda-store's documentation +# conda-store -conda-store is a set of open source tools for managing data science environments in collaborative teams. It provides flexible, yet reproducible, environments while enforcing best practices throughout your environment's life cycle. +The `conda-store` repository has two packages: -## Projects +- `conda-store-server`: the worker and web server responsible for the `conda-store` service +- `conda-store/`: the client which interacts with the service - - -- conda-store -- conda-store-ui -- jupyterlab-conda-store + diff --git a/docusaurus-docs/docusaurus.config.js b/docusaurus-docs/docusaurus.config.js index bccc46eb7..13714ffed 100644 --- a/docusaurus-docs/docusaurus.config.js +++ b/docusaurus-docs/docusaurus.config.js @@ -141,11 +141,11 @@ const config = { }, { label: "Governance", - to: "community/governance", + href: "https://github.com/conda-incubator/governance/tree/main", }, { label: "Support", - to: "community/support", + to: "community/introduction#support", }, ], }, diff --git a/docusaurus-docs/src/pages/index.js b/docusaurus-docs/src/pages/index.js index c496575bd..e66befb76 100644 --- a/docusaurus-docs/src/pages/index.js +++ b/docusaurus-docs/src/pages/index.js @@ -20,8 +20,8 @@ function HomepageHeader() {

{siteConfig.title}

{siteConfig.tagline}

- - Get Started + + Learn more