diff --git a/docs/contributing.md b/docs/contributing.md index d48021705..72c332509 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -196,7 +196,7 @@ Choose the `` number. It should follow [Semantic Versioning](https://semver.org/) and the established pattern of `v..`. -Ensure that `CHANGELOG.md` is up to date with all the changes since +Ensure that [`CHANGELOG.md`](https://github.com/conda-incubator/conda-store/blob/main/CHANGELOG.md) is up-to-date with all the changes since the last release following the template provided within the markdown file. diff --git a/docusaurus-docs/community/contribute/contribute-code.md b/docusaurus-docs/community/contribute/contribute-code.md index b6bdb045a..bdfe2e687 100644 --- a/docusaurus-docs/community/contribute/contribute-code.md +++ b/docusaurus-docs/community/contribute/contribute-code.md @@ -14,7 +14,7 @@ This page is in active development, content may be inaccurate and incomplete. Install the following dependencies before developing on conda-store. -- [docker](https://docs.docker.com/engine/install/) +- [Docker](https://docs.docker.com/engine/install/) - [docker-compose](https://docs.docker.com/compose/install/) To deploy `conda-store` run the following command @@ -26,8 +26,8 @@ docker-compose up --build -d :::important Many of the conda-store docker images are built/tested for amd64(x86-64) there will be a performance impact when building and running on -arm architectures. Otherwise this workflow has been shown to run and build on OSX. -Notice the `architecture: amd64` whithin the docker-compose.yaml files. +arm architectures. Otherwise, this workflow has been shown to run and build on OSX. +Notice the `architecture: amd64` within the `docker-compose.yaml` files. ::: The following resources will be available: @@ -43,7 +43,7 @@ The following resources will be available: On a fast machine this deployment should only take 10 or so seconds assuming the docker images have been partially built before. -If you are making and changes to conda-store-server and would like to see +If you are making any changes to `conda-store-server` and would like to see those changes in the deployment, run: ```shell @@ -55,7 +55,7 @@ docker-compose up --build 1. Install the following dependencies before developing on conda-store: -- [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/install/linux.html) + - [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/install/linux.html) 2. Install the development dependencies and activate the environment: @@ -69,11 +69,11 @@ conda activate conda-store-server-dev 3. Running `conda-store` in `--standalone` mode launches celery as a subprocess of the web server. -``` -python -m conda_store_server.server --standalone -``` + ```bash + python -m conda_store_server.server --standalone + ``` -4. Visit [localhost:8080](http://localhost:8080/) +1. Visit [localhost:8080](http://localhost:8080/) ## Set up development environment -- conda-store-ui @@ -81,20 +81,20 @@ To get started with conda-store-ui development, there are a couple of options. T ### Prerequisites -Before setting up conda-store ui, you must prepare your environment. +Before setting up conda-store-ui, you must prepare your environment. We use [Docker Compose](https://docs.docker.com/compose/) to set up the infrastructure before starting ensure that you have docker-compose installed. If you need to install docker-compose, please see their [installation documentation](https://docs.docker.com/compose/install/) 1. Clone the [conda-store-ui](https://github.com/conda-incubator/conda-store-ui.git) repository. -2. Copy `.env.example` to `.env`. All default settings should work, but if you want to test against a differenct version of conda-store-server, you can specify if in the `.env` file by setting the `CONDA_STORE_SERVER_VERSION` variable to the desired version +2. Copy `.env.example` to `.env`. All default settings should work, but if you want to test against a different version of conda-store-server, you can specify it in the `.env` file by setting the `CONDA_STORE_SERVER_VERSION` variable to the desired version ### Local Development with conda-store-ui running in Docker -Running conda-store-ui in Docker is the simplest way to setup your local development environment. +Running conda-store-ui in Docker is the simplest way to set up your local development environment. 1. Run `yarn run start:docker` to start the entire development stack. -2. Open you local browser and go to [http://localhost:8000](http://localhost:8000) so see conda-store-ui. -3. You can then login using the default username of `username` and default password of `password`. +Open your local browser and go to [http://localhost:8000](http://localhost:8000) so see conda-store-ui. +3. You can then log in using the default username of `username` and default password of `password`. **Note:** Hot reloading is enabled, so when you make changes to source files, your browser will reload and reflect the changes. @@ -113,8 +113,8 @@ This project uses [Conda](https://conda.io) for package management. To set up Co #### Run the application 1. Run `yarn run start` and wait for the application to finish starting up -2. Open you local browser and go to [http://localhost:8000](http://localhost:8000) so see conda-store-ui. -3. You can then login using the default username of `username` and default password of `password`. +Open your local browser and go to [http://localhost:8000](http://localhost:8000) so see conda-store-ui. +3. You can then log in using the default username of `username` and default password of `password`. **Note:** Hot reloading is enabled, so when you make changes to source files, your browser will reload and reflect the changes. diff --git a/docusaurus-docs/community/contribute/contribute-docs.md b/docusaurus-docs/community/contribute/contribute-docs.md index 4e1397f0b..ada490550 100644 --- a/docusaurus-docs/community/contribute/contribute-docs.md +++ b/docusaurus-docs/community/contribute/contribute-docs.md @@ -12,7 +12,7 @@ The new conda-store documentation website is built using [Docusaurus 2](https:// ### Pre-requisites 1. Fork and clone the conda-store repository: `git clone https://github.com//conda-store.git` -2. Install [Node.js](https://nodejs.org/en), and verify installation with: `node -v` +2. Install [Node.js](https://nodejs.org/en), and verify the installation with `node -`v` ### Local development @@ -20,7 +20,7 @@ The new conda-store documentation website is built using [Docusaurus 2](https:// You can also create an isolated environment for development. ::: -Navigate to `docusaurus-docs` repository, and run: +Navigate to the `/docusaurus-docs` directory, and run: ```bash npm install diff --git a/docusaurus-docs/community/contribute/issues.md b/docusaurus-docs/community/contribute/issues.md index 3b9d5c577..fcebb1dcf 100644 --- a/docusaurus-docs/community/contribute/issues.md +++ b/docusaurus-docs/community/contribute/issues.md @@ -4,7 +4,7 @@ description: Best practices for opening issues # Create and improve issues -## Submit bug report or feature request +## Submit a bug report or feature request The conda-store issue trackers are the preferred channel for bug reports, documentation requests, and submitting pull requests. @@ -32,7 +32,7 @@ A few more tips: - **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 `
`. +- **Sharing long blocks of code or logs**: If you need to include long code, logs or tracebacks, 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 @@ -46,10 +46,10 @@ If an issue is affecting you, start at the top of this list and complete as many 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. + OR if you can, write up a workaround 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. +4. [Optional] - Offer to help fix the issue (and it is expected that you ask for help; open-source maintainers want to help contributors). +5. [Optional] - If you decide to help fix the issue, deliver a well-crafted, tested PR. ## Improve existing issues @@ -60,7 +60,7 @@ 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. +- 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]. diff --git a/docusaurus-docs/community/contribute/testing.md b/docusaurus-docs/community/contribute/testing.md index 4b76e4f37..12de02587 100644 --- a/docusaurus-docs/community/contribute/testing.md +++ b/docusaurus-docs/community/contribute/testing.md @@ -46,7 +46,7 @@ $ cd conda-store-server $ hatch env run -e dev lint ``` -Checking that package builds +Checking that the package builds ```shell $ cd conda-store-server diff --git a/docusaurus-docs/community/maintenance/github-conventions.md b/docusaurus-docs/community/maintenance/github-conventions.md index 324553698..b253144d8 100644 --- a/docusaurus-docs/community/maintenance/github-conventions.md +++ b/docusaurus-docs/community/maintenance/github-conventions.md @@ -64,7 +64,7 @@ Here are a few guidelines for how to categorize impact across a few major types 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: low`: Useful but not a critical part of workflows. Is a niche use case that only a few users may need. **Bugs** @@ -72,7 +72,7 @@ Here are a few guidelines for how to categorize impact across a few major types (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. +- `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 @@ -110,28 +110,28 @@ 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 +- `good first issue`: these issues represent 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. +Pull requests are usually associated with or linked to issues. The natural path is to start with an issue and move on to 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. +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: stale 🥖`: a "stale" pull request 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. +GitHub notifies team members when labels are changed, so it is useful to keep the status of each pull request as close as possible to 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** diff --git a/docusaurus-docs/community/maintenance/release.md b/docusaurus-docs/community/maintenance/release.md index 5808173c6..a034aa232 100644 --- a/docusaurus-docs/community/maintenance/release.md +++ b/docusaurus-docs/community/maintenance/release.md @@ -56,7 +56,7 @@ For the release tag, there should be **NO** prepended `v`. Create an issue and copy & paste the steps below to release a new conda-store version. Close the issue when it is done. :::caution -There are two packages the [conda-store](https://github.com/conda-incubator/conda-store) repository; [`conda-store`](https://github.com/conda-incubator/conda-store/tree/main/conda-store) and [`conda-store-server`](https://github.com/conda-incubator/conda-store/tree/main/conda-store-server). Make sure to update both packages when releasing a new version. +There are two packages: the [conda-store](https://github.com/conda-incubator/conda-store) repository; [`conda-store`](https://github.com/conda-incubator/conda-store/tree/main/conda-store) and [`conda-store-server`](https://github.com/conda-incubator/conda-store/tree/main/conda-store-server). Make sure to update both packages when releasing a new version. ::: ```md @@ -82,7 +82,7 @@ Release captain responsible - <@gh_username> - [ ] Bump `conda-store` version in [`conda-store/conda-store/__init__.py`](https://github.com/conda-incubator/conda-store/blob/main/conda-store/conda_store/__init__.py) - [ ] Bump `conda-store-server` version in [`conda-store-server/conda-store-server/__init__.py`](https://github.com/conda-incubator/conda-store/blob/main/conda-store/conda_store/__init__.py) - [ ] Update the `conda-store-ui` version users in `conda-store-server` [`conda-store-server/hatch_build.py`](https://github.com/conda-incubator/conda-store/blob/main/conda-store-server/hatch_build.py) -- [ ] Update the [CHANGELOG.md](./CHANGELOG.md) file with the new version, release date, and relevant changes[^github-activity]. +- [ ] Update the [CHANGELOG.md](https://github.com/conda-incubator/conda-store/blob/main/CHANGELOG.md) file with the new version, release date, and relevant changes[^github-activity]. - [ ] Check the version locally with `hatch version` - [ ] Build and test locally - [ ] For `conda-store` and `conda-store-server`: @@ -105,7 +105,7 @@ Release captain responsible - <@gh_username> - Call the release the current version, e.g. `2023.9.1` - In the **`Choose a Tag:`** dropdown, type in the release name (e.g., `2023.9.1`) and click "Create new tag" - In the **`Target:`** dropdown, pin it to the release commit that you've recently pushed. - - Add release notes in the field below[^github-activity], you can copy/paste the changelog from the [CHANGELOG.md](./CHANGELOG.md) file. + - Add release notes in the field below[^github-activity], you can copy/paste the changelog from the [CHANGELOG.md](https://github.com/conda-incubator/conda-store/blob/main/CHANGELOG.md) file. - [ ] Confirm that the release completed - [The `release` GitHub action job](https://github.com/conda-incubator/conda-store/blob/main/.github/workflows/release.yaml) has completed successfully in the [actions tab](https://github.com/pydata/pydata-sphinx-theme/actions). - [The `conda-store` PyPI version is updated](https://pypi.org/project/conda-store/) diff --git a/docusaurus-docs/community/maintenance/reviewer-guidelines.md b/docusaurus-docs/community/maintenance/reviewer-guidelines.md index 4c2fed3cd..5b2b702c9 100644 --- a/docusaurus-docs/community/maintenance/reviewer-guidelines.md +++ b/docusaurus-docs/community/maintenance/reviewer-guidelines.md @@ -31,7 +31,7 @@ If you need help writing replies in reviews, check out our [standard replies for ## 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. +Note this is not an exhaustive, nor strict list of items to cover in each review, use your best judgment. - 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? @@ -45,11 +45,11 @@ Note this is not an exhaustive, nor strictly list of items to cover on each revi 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 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). + (focus on the larger issues, and 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`. @@ -67,16 +67,16 @@ Only maintainers can merge pull requests. Please follow these guidelines: - 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 +- You should typically not self-merge your 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 +- You should not merge pull requests that have an active discussion, or pull requests that have 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, +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. @@ -95,11 +95,11 @@ In your questions, try and be empathetic when phrasing. Instead of: "Why did you 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. +Try to focus and summarize in ways that 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. +It's okay to ask for changes to be made to 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. diff --git a/docusaurus-docs/community/maintenance/triage.md b/docusaurus-docs/community/maintenance/triage.md index 2502b40a5..e5d7d9295 100644 --- a/docusaurus-docs/community/maintenance/triage.md +++ b/docusaurus-docs/community/maintenance/triage.md @@ -13,7 +13,7 @@ Triage can happen asynchronously and continuously, or in regularly scheduled mee ## Why is triaging beneficial? -Projects that triage regularly say it offers a number of benefits, such as: +Projects that triage regularly say it offers several benefits, such as: - Speeding up issue management - Keeping contributors engaged by shortening response times @@ -54,7 +54,7 @@ You can also use the [conda-store project board](https://github.com/orgs/conda-i 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. + Detailed rationale for 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. diff --git a/docusaurus-docs/conda-store/introduction.md b/docusaurus-docs/conda-store/introduction.md index 67c9bec66..dfbe5d7f0 100644 --- a/docusaurus-docs/conda-store/introduction.md +++ b/docusaurus-docs/conda-store/introduction.md @@ -36,7 +36,7 @@ pip install conda-store conda-store-server -2. Start standalone local instance and use the conda-store UI +2. Start a standalone local instance and use the conda-store UI ```bash conda-store-server --standalone