Update Tutorials and How-to contributing pages

docs/source/conf.py

@@ -42,6 +42,7 @@
     "sphinx_copybutton",
     "jupyter_sphinx",
     "sphinxcontrib.youtube",
+    "sphinx_togglebutton",
 ]
 
 # codeautolink

docs/source/contributing/how_to_release.md

@@ -1,71 +1,55 @@
 # How to make a new release
 
-ArviZ uses the following process to cut a new release of the library.
+ArviZ uses the following process to cut a new release of the ArviZverse packages.
 
-1. Bump the version number in `arviz/__init__.py`
+1. Bump the version number in `src/<arviz repo>/__init__.py` or `src/<arviz repo>/_version.py`
 
    ```diff
-   - __version = "0.12.0"
-   + __version = "0.12.1"
+   - __version = "1.2.0"
+   + __version = "1.2.1"
    ```
 
-2. Update the release notes in `CHANGELOG.md`. Remove any subsections within the released version
-   without any items within them.
+2. Check versions in `pyproject.toml`. Arviz aims to follow the recommendations in [SPEC-0](https://scientific-python.org/specs/spec-0000/) from scientific python.
 
-   ```diff
-   - ## v0.x.x Unreleased
-   + ## v0.12.1 (2022 May 12)
-   ```
-
-   Empty subheadings for the "unreleased" development version don't need to be included yet.
-
-3. Check versions in `requirements.txt` and `setup.py` files. Arviz aims to follow the recommendations in [SPEC-0](https://scientific-python.org/specs/spec-0000/) from scientific python.
+3. Open a Pull Request including these changes. Make sure all CI tests pass, adding commits if necessary.
+   Even if CI is passing on main, there might be new releases of dependencies that break CI.
 
-4. Open a Pull Request including these changes. Make sure all CI tests pass, adding commits if necessary. Even if CI is passing on main, there might be new releases of dependencies that break CI.
+   :::{important}
+   The documentation build should also complete successfully. If we publish a release from a commit
+   where the docs don't build we then have to choose between that version not showing in the
+   version switcher or publishing a patch release that fixes the doc build.
+   :::
 
-5. Add a release in the Github [release page](https://github.com/arviz-devs/arviz/releases) once the PR is merged.
+4. Add a release in the Github [release page](https://github.com/arviz-devs/arviz/releases) once the PR is merged.
 
-6. After the release on Github, the CI system will complete the rest of the steps. Including making any wheels and uploading the new version to PyPI.
+5. After the release on Github, the CI system will complete the rest of the steps. Including making any wheels and uploading the new version to PyPI.
+   It will also add a PR to update the changelog.
 
-7. Add a follow-up PR changing the version string to include the dev flag.
+6. Add a follow-up PR changing the version string to include the dev flag.
    Make sure the version string is [PEP 440](https://peps.python.org/pep-0440/#appendix-b-parsing-version-strings-with-regular-expressions) compliant.
    For example, after releasing `v0.12.1` it should be set to `0.13.0.dev0`.
 
-8. Use the following template to add empty subheadings to the `CHANGELOG.md` file in the follow-up PR.
-
-   ```markdown
-   ## v0.x.x Unreleased
-
-   ### New features
-
-   ### Maintenance and fixes
-
-   ### Deprecation
-
-   ### Documentation
-   ```
-
-9. If the versions were updated in step 3, update also the [conda forge recipe](https://github.com/conda-forge/arviz-feedstock).
+7. If the versions were updated in step 3, update also the [conda forge recipe](https://github.com/conda-forge/arviz-feedstock).
 
    :::{important}
    There is a bot that opens a PR automatically to update the conda forge recipe.
-   However, **all dependencies must be checked manually** to ensure the ones in
-   the recipe match those in the requirements
+   There is a second bot that also attempts to update dependecies automatically from `pyproject.toml`,
+   however, at the time of writing it is experimental, so we always need to double check dependencies.
    :::
 
-10. (here for reference but we really want to avoid it) If for some reason there were an issue
-    with a release, there are two tools to fix it in conda forge:
+8. (here for reference but we really want to avoid it) If for some reason there were an issue
+   with a release, there are two tools to fix it in conda forge:
 
-    * repodata patch: If there is a new release for one of the dependencies with breaking changes
-      for example, a repodata patch should be submitted to conda forge to prevent users
-      from installing a broken environment.
+   * repodata patch: If there is a new release for one of the dependencies with breaking changes
+     for example, a repodata patch should be submitted to conda forge to prevent users
+     from installing a broken environment.
 
-      Repodata patches are submitted to [conda-forge/conda-forge-repodata-patches-feedstock](https://github.com/conda-forge/conda-forge-repodata-patches-feedstock)
-    * mark a build as broken: If the dependencies were incorrect in the recipe, then the existing
-      build should be marked as broken and a PR (completely manual) should be submitted
-      to the arviz-feedstock to fix the recipe. Note that if this is being done for a release
-      different than the latest, changes should not be merged into `main` but on a dedicated
-      branch, the conda-forge package build is generated all the same but the history is kept
-      tidier and prevents issues when a new release is published.
+     Repodata patches are submitted to [conda-forge/conda-forge-repodata-patches-feedstock](https://github.com/conda-forge/conda-forge-repodata-patches-feedstock)
+   * mark a build as broken: If the dependencies were incorrect in the recipe, then the existing
+     build should be marked as broken and a PR (completely manual) should be submitted
+     to the arviz-feedstock to fix the recipe. Note that if this is being done for a release
+     different than the latest, changes should not be merged into `main` but on a dedicated
+     branch, the conda-forge package build is generated all the same but the history is kept
+     tidier and prevents issues when a new release is published.
 
-      Requests to mark packages as broken are submitted to [conda-forge/admin-requests](https://github.com/conda-forge/admin-requests/)
+     Requests to mark packages as broken are submitted to [conda-forge/admin-requests](https://github.com/conda-forge/admin-requests/)

docs/source/contributing/pr_tutorial.md

@@ -5,29 +5,54 @@ The preferred workflow for contributing to ArviZ is to fork
 the [GitHub repository](https://github.com/arviz-devs/arviz/),
 clone it to your local machine, and develop on a feature branch.
 
+This tutorial applies to any of these repositories:
+
+* [arviz-devs/arviz](https://github.com/arviz-devs/arviz)
+* [arviz-devs/arviz-base](https://github.com/arviz-devs/arviz-base)
+* [arviz-devs/arviz-stats](https://github.com/arviz-devs/arviz-stats)
+* [arviz-devs/arviz-plots](https://github.com/arviz-devs/arviz-plots)
+
+
 (pr_steps)=
 ## Steps
 
-1. Fork the [project repository](https://github.com/arviz-devs/arviz/) by clicking on the 'Fork' button near the top right of the main repository page. This creates a copy of the code under your GitHub user account.
+:::{admonition} Have you already gone through this tutorial?
+:class: dropdown tip
+
+If this is not your first time going over this tutorial and you want to
+work on your 2nd+ PR you can skip steps 1-3, and instead do:
+
+```bash
+git checkout main
+git fetch upstream
+git rebase upstream/main
+```
+
+This will make sure you are on the `main` branch of your local repository and sync it
+with the one on GitHub. After this you can continue with {ref}`step 4 <feature_branch_step_pr>`
+to create your feature branch from the up-to-date `main`
+:::
+
+1. Fork the project repository by clicking on the 'Fork' button near the top right of the main repository page. This creates a copy of the code under your GitHub user account.
 
 (fork_step_pr)=
-2. Clone your fork of the ArviZ repo from your GitHub account to your local disk.
+2. Clone your fork of the target ArviZ repository from your GitHub account to your local disk.
 
    ::::{tab-set}
 
    :::{tab-item} SSH
    :sync: ssh
 
    ```
-   git clone git@github.com:<your GitHub handle>/arviz.git
+   git clone git@github.com:<your GitHub handle>/<arviz repo>.git
    ```
    :::
 
    :::{tab-item} HTTPS
    :sync: https
 
    ```
-   git clone https://github.com/<your GitHub handle>/arviz.git
+   git clone https://github.com/<your GitHub handle>/<arviz repo>.git
    ```
    :::
 
@@ -41,17 +66,17 @@ clone it to your local machine, and develop on a feature branch.
    :sync: ssh
 
    ```
-   cd arviz
-   git remote add upstream git@github.com:arviz-devs/arviz.git
+   cd <arviz repo>
+   git remote add upstream git@github.com:arviz-devs/<arviz repo>.git
    ```
    :::
 
    :::{tab-item} HTTPS
    :sync: https
 
    ```
-   cd arviz
-   git remote add upstream https://github.com/arviz-devs/arviz.git
+   cd <arviz repo>
+   git remote add upstream https://github.com/arviz-devs/<arviz repo>.git
    ```
    :::
 
@@ -66,28 +91,59 @@ clone it to your local machine, and develop on a feature branch.
 
    ```{warning}
    Always create a new ``feature`` branch before making any changes. Make your changes
-   in the ``feature`` branch. It's good practice to never routinely work on the ``main`` branch of any repository.
+   in the ``feature`` branch. It's good practice to never routinely work on the ``main`` branch of any repository
+   and we have a pre-commit check that prevents committing to `main`
    ```
 
-5. Project requirements are defined in pyproject.toml. Libraries used for development and       documentation are provided as optional dependency groups. To set up a development environment, you may (probably in a [virtual environment](https://docs.python-guide.org/dev/virtualenvs/)) run:
+5. We use [tox](https://tox.wiki/en/latest/index.html) to help with common development tasks.
+   To get your development environment up and running we recommend installing `tox` and the
+   arviz local package you are working on:
 
    ```bash
+   pip install tox
    pip install -e .
-   pip install -e .[test,check]
-   pip install -e .[doc]  # to generate docs locally
    ```
 
-   Alternatively, for developing the project in [Docker](https://docs.docker.com/), there is a script to setup the Docker environment for development. See {ref}`developing_in_docker`.
+6. Work on your feature, bugfix, documentation improvement...
 
-6. Develop the feature on your feature branch. Add your changes using git commands, ``git add`` and then ``git commit``, like:
+7. Execute the relevant development related tasks. Each repository has slightly different needs
+   for testing or doc building so we start by checking the available tox commands:
+
+   ```bash
+   tox list -m dev
+   ```
+
+   which will print something like:
+
+   ```none
+   check          -> Perform style checks
+   docs           -> Build HTML docs
+   test-namespace -> Run ArviZ metapackage tests
+   cleandocs      -> Clean HTML doc build outputs
+   viewdocs       -> View HTML docs with the default browser
+   ```
+
+   we then execute the relevant commands. If we have been working a bugfix and didn't
+   change anything related to documentation we can skip those tasks and run only the
+   `check` and `test-namespace` ones:
+
+   ```bash
+   tox -e test-namespace
+   tox -e check
+   ```
+
+(commit_push_step_pr)=
+6. Once you are happy with the changes, add your changes using git commands,
+   ``git add`` and then ``git commit``, like:
 
    ```bash
    git add modified_files
    git commit -m "commit message here"
    ```
 
-   to record your changes locally.
-   After committing, it is a good idea to sync with the base repository in case there have been any changes:
+   to record your changes locally. After committing, it is a good idea to sync with the base
+   repository in case there have been any changes:
+
    ```bash
    git fetch upstream
    git rebase upstream/main
@@ -99,8 +155,18 @@ clone it to your local machine, and develop on a feature branch.
    git push -u origin my-feature
    ```
 
-7. Go to the GitHub web page of your fork of the ArviZ repo. Click the 'Pull request' button to send your changes to the project's maintainers for review. This will send an email to the committers.
+7. Go to the GitHub web page of the respective ArviZ repository you were working on.
+   Click the 'Pull request' button to send your changes to the project's maintainers for review.
+   This will send an email to the committers.
 
    :::{tip}
    Now that the PR is ready to submit, check the {ref}`pr_checklist`.
    :::
+
+8. Thanks for contributing! {octicon}`heart-fill` Now Wait for reviews to come it.
+   Most reviewers work on ArviZ on a volunteer basis, depending on availability and
+   workload it can take several days until you get a review.
+
+9. Address review comments. Some PRs can be merged directly, but the most common scenario
+   if for further commits to be needed. To update your PR you only need to commit to the
+   same branch you were working on and push as shown in {ref}`step 6 <commit_push_step_pr>`.