fast-forward cookiecutter

.cruft.json

@@ -1,6 +1,6 @@
 {
   "template": "https://github.com/Ouranosinc/cookiecutter-pypackage",
-  "commit": "65a4313b060df132d83623006c5d7241ba734d9b",
+  "commit": "844fb9600b45d5d51d6e88dfdc4acdf88aa09bac",
   "checkout": null,
   "context": {
     "cookiecutter": {

.github/workflows/bump-version.yml

@@ -48,7 +48,7 @@ jobs:
         run: |
           pip install bump-my-version
           echo "Bumping version"
-          bump-my-version bump patch
+          bump-my-version bump --tag patch
           echo "new_version=$(grep -E '__version__'  figanos/__init__.py | cut -d ' ' -f3)"
       - name: Push Changes
         uses: ad-m/github-push-action@master

.github/workflows/main.yml

@@ -93,7 +93,7 @@ jobs:
         run: |
           mamba --version
           echo "micromamba $(micromamba --version)"
-      - name: Compile catalogs and install xscen
+      - name: Compile catalogs and install figanos
         run: |
           python -m pip install --no-deps .
       - name: Check versions

CONTRIBUTING.rst

@@ -50,7 +50,22 @@ If you are proposing a feature:
   are welcome :)
 
 Get Started!
--------------------------------------------------
+------------
+
+.. note::
+
+    If you are new to using GitHub and `git`, please read `this guide <https://guides.github.com/activities/hello-world/>`_ first.
+
+.. warning::
+
+    Anaconda Python users: Due to the complexity of some packages, the default dependency solver can take a long time to resolve the environment. Consider running the following commands in order to speed up the process::
+
+        $ conda install -n base conda-libmamba-solver
+        $ conda config --set solver libmamba
+
+    For more information, please see the following link: https://www.anaconda.com/blog/a-faster-conda-for-a-growing-community
+
+    Alternatively, you can use the `mamba <https://mamba.readthedocs.io/en/latest/index.html>`_ package manager, which is a drop-in replacement for ``conda``. If you are already using `mamba`, replace the following commands with ``mamba`` instead of ``conda``.
 
 Ready to contribute? Here's how to set up ``figanos`` for local development for developers outside Ouranos.
 
@@ -59,62 +74,74 @@ Ready to contribute? Here's how to set up ``figanos`` for local development for
 
     $ git clone git@github.com:your_name_here/figanos.git
 
-#. Install your local copy into a development environment. Using ``mamba``, you can create a new development environment with::
+#. Install your local copy into a development environment. You can create a new Anaconda development environment with::
 
-    $ mamba env create -f environment-dev.yml
+    $ conda env create -f environment-dev.yml
     $ conda activate figanos
     $ flit install --symlink
 
-#. To ensure a consistent style, please install the pre-commit hooks to your repo::
+  This installs ``figanos`` in an "editable" state, meaning that changes to the code are immediately seen by the environment.
+
+#. To ensure a consistent coding style, install the ``pre-commit`` hooks to your local clone::
 
     $ pre-commit install
 
-   Special style and formatting checks will be run when you commit your changes. You
-   can always run the hooks on their own with:
+  On commit, ``pre-commit`` will check that ``black``, ``blackdoc``, ``isort``, ``flake8``, and ``ruff`` checks are passing, perform automatic fixes if possible, and warn of violations that require intervention. If your commit fails the checks initially, simply fix the errors, re-add the files, and re-commit.
+
+  You can also run the hooks manually with::
 
     $ pre-commit run -a
 
+  If you want to skip the ``pre-commit`` hooks temporarily, you can pass the ``--no-verify`` flag to `$ git commit`.
+
 #. Create a branch for local development::
 
     $ git checkout -b name-of-your-bugfix-or-feature
 
-   Now you can make your changes locally.
+  Now you can make your changes locally.
 
-#. When you're done making changes, check that your changes pass ``black``, ``blackdoc``, ``flake8``, ``isort``, ``ruff``, and the tests, including testing other Python versions with tox::
+#. When you're done making changes, we **strongly** suggest running the tests in your environment or with the help of ``tox``::
 
-    $ black --check figanos tests
-    $ isort --check figanos tests
-    $ ruff figanos tests
-    $ flake8 figanos tests
-    $ blackdoc --check figanos docs
     $ python -m pytest
+    # Or, to run multiple build tests
     $ tox
 
-   To get ``black``, ``blackdoc``, ``flake8``, ``isort``, ``ruff``, and tox, just pip install them into your virtualenv.
-
 #. Commit your changes and push your branch to GitHub::
 
     $ git add .
     $ git commit -m "Your detailed description of your changes."
     $ git push origin name-of-your-bugfix-or-feature
 
-#. If you are editing the docs, compile and open them with::
+  If ``pre-commit`` hooks fail, try re-committing your changes (or, if need be, you can skip them with `$ git commit --no-verify`).
+
+#. Submit a `Pull Request <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request>`_ through the GitHub website.
+
+#. When pushing your changes to your branch on GitHub, the documentation will automatically be tested to reflect the changes in your Pull Request. This build process can take several minutes at times. If you are actively making changes that affect the documentation and wish to save time, you can compile and test your changes beforehand locally with::
 
+    # To generate the html and open it in your browser
     $ make docs
-    # or to simply generate the html
-    $ cd docs/
-    $ make html
+    # To only generate the html
+    $ make autodoc
+    $ make -C docs html
+    # To simply test that the docs pass build checks
+    $ tox -e docs
+
+#. Once your Pull Request has been accepted and merged to the ``main`` branch, several automated workflows will be triggered:
+
+    - The ``bump-version.yml`` workflow will automatically bump the patch version when pull requests are pushed to the ``main`` branch on GitHub. **It is not recommended to manually bump the version in your branch when merging (non-release) pull requests (this will cause the version to be bumped twice).**
+    - `ReadTheDocs` will automatically build the documentation and publish it to the `latest` branch of `figanos` documentation website.
+    - If your branch is not a fork (ie: you are a maintainer), your branch will be automatically deleted.
 
-#. Submit a pull request through the GitHub website.
+  You will have contributed your first changes to ``figanos``!
 
 Pull Request Guidelines
 -----------------------
 
 Before you submit a pull request, check that it meets these guidelines:
 
-#. The pull request should include tests.
+#. The pull request should include tests and should aim to provide `code coverage <https://en.wikipedia.org/wiki/Code_coverage>`_ for all new lines of code. You can use the ``--cov-report html --cov figanos`` flags during the call to ``pytest`` to generate an HTML report and analyse the current test coverage.
 
-#. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in ``README.rst``.
+#. If the pull request adds functionality, the docs should also be updated. Put your new functionality into a function with a docstring, and add the feature to the list in ``README.rst``.
 
 #. The pull request should work for Python 3.8, 3.9, 3.10, and 3.11. Check that the tests pass for all supported Python versions.
 
@@ -126,33 +153,49 @@ To run a subset of tests::
 
 $ pytest tests.test_figanos
 
+To run specific code style checks::
+
+    $ black --check figanos tests
+    $ isort --check figanos tests
+    $ blackdoc --check figanos docs
+    $ ruff figanos tests
+    $ flake8 figanos tests
+
+To get ``black``, ``isort ``blackdoc``, ``ruff``, and ``flake8`` (with plugins ``flake8-alphabetize`` and ``flake8-rst-docstrings``) simply `$ pip install` them into your environment.
+
 Versioning/Tagging
 ------------------
 
-A reminder for the maintainers on how to deploy. This section is only relevant for maintainers when they are producing a new point release for the package.
+A reminder for the **maintainers** on how to deploy. This section is only relevant when producing a new point release for the package.
+
+.. warning::
+
+    It is important to be aware that any changes to files found within the ``figanos`` folder (with the exception of ``figanos/__init__.py``) will trigger the ``bump-version.yml`` workflow. Be careful not to commit changes to files in this folder when preparing a new release.
 
 #. Create a new branch from `main` (e.g. `release-0.2.0`).
 #. Update the `CHANGES.rst` file to change the `Unreleased` section to the current date.
-#. Create a pull request from your branch to `main`.
-#. Once the pull request is merged, create a new release on GitHub. On the main branch, run:
+#. Bump the version in your branch to the next version (e.g. `v0.1.0 -> v0.2.0`)::
 
     .. code-block:: shell
 
         $ bump-my-version bump minor # In most cases, we will be releasing a minor version
         $ git push
-        $ git push --tags
 
-    This will trigger the CI to build the package and upload it to TestPyPI. In order to upload to PyPI, this can be done by publishing a new version on GitHub. This will then trigger the workflow to build and upload the package to PyPI.
+#. Create a pull request from your branch to `main`.
+#. Once the pull request is merged, create a new release on GitHub. On the main branch, run:
 
-#. Once the release is published, it will go into a `staging` mode on Github Actions. Once the tests pass, admins can approve the release (an e-mail will be sent) and it will be published on PyPI.
+    .. code-block:: shell
 
-.. note::
+        $ git tag v0.2.0
+        $ git push --tags
 
-    The ``bump-version.yml`` GitHub workflow will automatically bump the patch version when pull requests are pushed to the ``main`` branch on GitHub. It is not necessary to manually bump the version in your branch when merging (non-release) pull requests.
+   This will trigger a GitHub workflow to build the package and upload it to TestPyPI. At the same time, the GitHub workflow will create a draft release on GitHub. Assuming that the workflow passes, the final release can then be published on GitHub by finalizing the draft release.
+
+#. Once the release is published, the `publish-pypi.yml` workflow will go into an `awaiting approval` mode on Github Actions. Only authorized users may approve this workflow (notifications will be sent) to trigger the upload to PyPI.
 
 .. warning::
 
-    It is important to be aware that any changes to files found within the ``figanos`` folder (with the exception of ``figanos/__init__.py``) will trigger the ``bump-version.yml`` workflow. Be careful not to commit changes to files in this folder when preparing a new release.
+    Uploads to PyPI can **never** be overwritten. If you make a mistake, you will need to bump the version and re-release the package. If the package uploaded to PyPI is broken, you should modify the GitHub release to mark the package as broken, as well as yank the package (mark the version  "broken") on PyPI.
 
 Packaging
 ---------

README.rst

@@ -25,7 +25,6 @@ Pour nous partager vos codes à ajouter dans figanos, s.v.p créer un issue sur
 * Free software: Apache Software License 2.0
 * Documentation: https://figanos.readthedocs.io.
 
-
 Features
 --------
 

pyproject.toml

@@ -55,6 +55,7 @@ dev = [
   "bump-my-version>=0.12.0",
   "watchdog>=3.0.0",
   "flake8>=6.1.0",
+  "flake8-alphabetize>=0.0.21",
   "flake8-rst-docstrings>=0.3.0",
   "flit",
   "tox>=4.5.1",
@@ -106,7 +107,7 @@ target-version = [
 [tool.bumpversion]
 current_version = "0.2.0"
 commit = true
-tag = true
+tag = false
 tag_name = "{new_version}"
 allow_dirty = false
 serialize = ["{major}.{minor}.{patch}"]