[DOC] Update contributing guidelines

docusaurus-docs/community/contribute/contribute-code.md

@@ -1,142 +1,129 @@
 ---
-description: Contribute to conda-store's codebase
+sidebar_position: 1
+description: Guidelines for contributing to various conda-store projects
 ---
 
-# Contribute code
+# Code contribution workflow
 
-:::warning
-This page is in active development, content may be inaccurate and incomplete.
-:::
+We welcome all code contributions to conda-store projects.
+This document describes the steps for making successful contributions.
 
-## Set up development environment - conda-store-core
+## Select (or open) an issue
 
-### Docker (recommended)
+The issues marked with the "good first issue" label are a great place to start. These bug reports and feature requests have a low entry-barrier, need little historical context, and are self-contained. Select a project and "good first issue" that matches your interest and skill set.
 
-Install the following dependencies before developing on conda-store.
+conda-store development happens across three repositories, and the relevant programming language and technologies are listed below:
 
-- [Docker](https://docs.docker.com/engine/install/)
-- [docker-compose](https://docs.docker.com/compose/install/)
+* `conda-store` and `conda-store-server`: Python, FastAPI, and conda ecosystem
+* `conda-store-ui`: Typescript, React, and frontend web development
+* `jupyterlab-conda-store`: JupyterLab extension development (Typescript and Javascript)
 
-To deploy `conda-store` run the following command
+:::note
+If the issue you are interested in is "assigned" to someone, it means they plan to work on it. In this case, select a different issue or comment on the issue asking the assignee if they are OK with you taking over.
+:::
 
-```shell
-docker-compose up --build -d
-```
+If you feel comfortable contributing the fix/feature directly, write a comment on the issue to let the community know that you are working on it. If you need more context or help with the issue (at any point in your contribution), feel free to ask questions on the same issue.
 
-:::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` within the `docker-compose.yaml` files.
-:::
+If your contributing involves significant API changes, write a comment on the issue describing your proposal for implementation. This allows us to discuss the details and confirm the changes beforehand, and respect the time and energy you spend contributing.
 
-The following resources will be available:
+The project maintainers are always happy to support you! Please be patient while maintainers get back to your questions, but you can drop a reminder after about 4 working days if no one has replied to you. :)
 
-| Resource | Localhost port | username | password |
-|----------|----------------|----------|----------|
-| conda-store web server | [localhost:8080](http://localhost:8080)| `admin` | `password`|
-| [JupyterHub](https://jupyter.org/hub) | [localhost:8000](http://localhost:8000) | any | `test` |
-| [MinIO](https://min.io/) S3 |  [localhost:9000](http://localhost:9000) | `admin` | `password` |
-| [PostgreSQL](https://www.postgresql.org/) (database: `conda-store`)| [localhost:5432](http://localhost:5432) | `admin` | `password` |
-| [Redis](https://www.redis.com/) |  [localhost:6379](http://localhost:6379) | - | password |
+:::warning
+If you want to work on a specific bug or feature that does not have issue, start by [opening a new issue][open-issue] and discussing it before working on it.
+:::
 
-On a fast machine this deployment should only take 10 or so seconds
-assuming the docker images have been partially built before.
+## Setup for local development
 
-If you are making any changes to `conda-store-server` and would like to see
-those changes in the deployment, run:
+:::tip
+Optionally, you can use tools like conda, pipenv, or venv to create an isolated environment for development.
+:::
 
-```shell
-docker-compose down -v # not always necessary
-docker-compose up --build
-```
+### Fork and clone the repository
 
-### Linux
+1. Create a personal copy of the corresponding conda-store GitHub repository by clicking the fork button in the top-right corner.
 
-1. Install the following dependencies before developing on conda-store:
+2. Clone the forked project to your local computer:
 
-   - [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/install/linux.html)
+```bash
+git clone https://github.com/<your-username>/<conda-store-repo-name>.git
+```
 
-2. Install the development dependencies and activate the environment:
+1. Navigate to the project directory.
 
-```shell
-# replace this with environment-macos-dev.yaml or environment-windows-dev.yaml
-# if you are on Mac or Windows
-conda env create -f conda-store-server/environment-dev.yaml
-conda activate conda-store-server-dev
+```bash
+cd <conda-store-repo-name>
 ```
 
-3. Running `conda-store` in `--standalone` mode launches celery as a
-subprocess of the web server.
+4. Add the upstream repository:
 
-    ```bash
-    python -m conda_store_server.server --standalone
-   ```
+```bash
+git remote add upstream https://github.com/conda-incubator/<conda-store-repo-name>.git
+```
 
-1. Visit [localhost:8080](http://localhost:8080/)
+5. Now the command `git remote -v` shows two remote repositories:
 
-## Set up development environment -- conda-store-ui
+* **upstream:** which refers to the conda-store repository on GitHub.
+* **origin:** which refers to your personal fork.
 
-To get started with conda-store-ui development, there are a couple of options. This guide will help you to set up your local development environment.
+### Install library for development
 
-### Prerequisites
+Follow the steps for the corresponding project to create a development installation:
 
-Before setting up conda-store-ui, you must prepare your environment.
+* [Local setup for conda-store (core)][local-install-conda-store]
+* [conda-store-ui][local-install-conda-store-ui]
+* [jupyterlab-conda-store][local-install-jlab-conda-store]
 
-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/)
+## Develop your contribution
 
-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 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
+1. Before you start, make sure to pull the latest changes from upstream.
 
-### Local Development with conda-store-ui running in Docker
+```bash
+git checkout develop
+git pull upstream develop
+```
 
-Running conda-store-ui in Docker is the simplest way to set up your local development environment.
+2. Create a branch for the bug or feature you want to work on. The branch name will appear in the merge message, so use a sensible, self-explanatory name:
 
-1. Run `yarn run start:docker` to start the entire development stack.
-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`.
+```bash
+git branch feature/<feature name>
+git switch feature/<feature name>
+# this is an alternative to the git checkout -b feature/<feature name> command
+```
 
-**Note:** Hot reloading is enabled, so when you make changes to source files, your browser will reload and reflect the changes.
+3. Commit locally as you progress (`git add` and `git commit`), and make sure to use an adequately formatted commit message.
 
-### Local Development without running conda-store-ui in Docker
+## Test your contribution
 
-This setup still uses Docker for supporting services but runs conda-store-ui locally.
+The local setup instructions for the projects also include instructions for testing.
+Make sure to test your contributions locally for more efficient code reviews.
 
-#### Set up your environment
+## Open a pull requests (PRs)
 
-This project uses [Conda](https://conda.io) for package management. To set up Conda, please see their [installation documentation](https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html).
-1. Change to the project root ` cd conda-store-ui`
-2. From the project root create the conda environment `conda env create -f environment_dev.yml`
-3. Activate the development environment `conda activate cs-ui-dev-env`
-4. Install yarn dependencies `yarn install`
+When you feel comfortable with your contribution, you can open a pull request (PR) to submit it for review
 
-#### Run the application
+You can also submit partial work to get early feedback on your contribution or discuss some implementation details. If you do so, add WIP (work in progress) in the PR title or add the "status: in progress 🏗" label, and mark it as a draft.
 
-1. Run `yarn run start` and wait for the application to finish starting up
-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`.
+Push your changes back to your fork on GitHub:
 
-**Note:** Hot reloading is enabled, so when you make changes to source files, your browser will reload and reflect the changes.
+```bash
+git push origin <feature/feature name>
+```
 
-<!-- TODO
+Enter your GitHub username and password (repeat contributors or advanced users can remove this step by connecting to GitHub with SSH).
 
-## jupyterlab-conda-store
+Go to the corresponding conda-store repository on GitHub. You will see a green pull request button. Make sure the title and message are clear, concise, and self-explanatory. Complete the checklist and read the notes in the PR template, then click the button to submit it.
 
--->
+:::note
+If the PR relates to any issues, you can add the text xref gh-xxxx where xxxx is the issue number to GitHub comments. Likewise, if the PR solves an issue, replace the xref with closes, fixes or any other flavors GitHub accepts. GitHub will automatically close the corresponding issue(s) when your PR gets merged.
+:::
 
-## Workflows
+## Code review
 
-### Changes to API
+Reviewers (the other developers and interested community members) will write inline and general comments on your pull request (PR) to help you improve its implementation, documentation, and style. Every developer working on the project has their code reviewed, and we've come to see it as a friendly conversation from which we all learn and the overall code quality benefits. Therefore, please don't let the review discourage you from contributing: its only aim is to improve the quality of the project, not to criticize (we are, after all, very grateful for the time you're donating!).
 
-The REST API is considered somewhat stable. If any changes are made to
-the API make sure the update the OpenAPI/Swagger specification in
-`docs/_static/openapi.json`. This may be downloaded from the `/docs`
-endpoint when running conda-store. Ensure that the
-`c.CondaStoreServer.url_prefix` is set to `/` when generating the
-endpoints.
-<!-- TODO -->
+To update your PR to incorporate the suggestions, make your changes on your local repository, commit them, run tests, and only if they succeed, push to your fork. The PR will update automatically as soon as those changes are pushed up (to the same branch as before).
 
-## Workflows
+## Guidelines for specific workflows
 
 ### Changes to API
 
@@ -146,3 +133,10 @@ the API make sure the update the OpenAPI/Swagger specification in
 endpoint when running conda-store. Ensure that the
 `c.CondaStoreServer.url_prefix` is set to `/` when generating the
 endpoints.
+
+<!-- Internal links -->
+
+[open-issues]: /community/contribute/issues
+[local-install-conda-store]: /community/contribute/local-setup-core
+[local-install-conda-store-ui]: /community/contribute/local-setup-ui
+[local-install-jlab-conda-store]: /community/contribute/local-setup-labextension

docusaurus-docs/community/contribute/contribute-docs.md

@@ -1,25 +1,42 @@
 ---
+sidebar_position: 2
 description: Contribute to conda-store's documentation
 ---
 
-> **Note**
-> This page in active development.
+# Contribute documentation
 
-The new conda-store documentation website is built using [Docusaurus 2](https://docusaurus.io/) and organized using the [Diátaxis  framework](https://diataxis.fr).
+The documentation website is built using [Docusaurus 3][docusaurus] and organized using the [Diátaxis  framework][diataxis] for each conda-store library.
 
-## Local Development
+## Style guidelines
+
+conda-store documentation follows the [Nebari documentation style guide][nebari-style-guide] including the [capitalization preferences][nebari-style-guide-capitalization], which in-turn derives from the [Google developer documentation style guide][google-style-guide].
+
+## Documentation structure
+
+All three conda-store libraries are documented in the [`conda-store` GitHub repository][cs-github], in the `docusaurus-docs` folder with each library in a separate sub-folder.
+
+## Contribution process
+
+Similar to code contributions, you can open issues to track as discuss documentation updates and file pull requests to contribute changes.
+
+## Local development setup
 
 ### Pre-requisites
 
 1. Fork and clone the conda-store repository: `git clone https://github.com/<your-username>/conda-store.git`
-2. Install [Node.js](https://nodejs.org/en), and verify the installation with `node -`v`
+2. Install [Node.js][nodejs], and verify the installed version with `node -v`.
 
-### Local development
+:::tip
+To create and activate an isolated conda environment with nodejs, run:
 
-:::note
-You can also create an isolated environment for development.
+```bash
+conda create -n conda-store-docs nodejs
+conda activate conda-store-docs
+```
 :::
 
+### Local development
+
 Navigate to the  `/docusaurus-docs` directory, and run:
 
 ```bash
@@ -32,14 +49,32 @@ You can then start a development server with the following:
 npm run start
 ```
 
-This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+This command starts a local development server at [localhost:3000](http://localhost:3000) which opens automatically in a new browser window. Most changes are reflected live without having to restart the server.
 
 ### Build website
 
-Run:
+:::note
+This is rarely required during development, but can be useful for verifying certain changes. The static files should **not** be committed to the repository.
+:::
+
+To build the website locally, run:
 
 ```bash
 npm run build
 ```
 
 This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+Currently, conda-store docs are deployed using [Netlify][netlify].
+
+
+<!-- External links -->
+
+[docusaurus]: https://www.nebari.dev/docs/community/style-guide
+[diataxis]: https://diataxis.fr
+[nebari-style-guide]: https://www.nebari.dev/docs/community/style-guide
+[nebari-style-guide-capitalization]: https://www.nebari.dev/docs/community/style-guide#capitalization
+[google-style-guide]: https://developers.google.cn/style
+[nodejs]: https://nodejs.org/en
+[netlify]: https://www.netlify.com
+[cs-github]: https://github.com/conda-incubator/conda-store

docusaurus-docs/community/contribute/issues.md

@@ -1,4 +1,5 @@
 ---
+sidebar_position: 3
 description: Best practices for opening issues
 ---