diff --git a/{{cookiecutter.project_slug}}/CONTRIBUTING.rst b/{{cookiecutter.project_slug}}/CONTRIBUTING.rst index 497806d22..5c157bb8c 100644 --- a/{{cookiecutter.project_slug}}/CONTRIBUTING.rst +++ b/{{cookiecutter.project_slug}}/CONTRIBUTING.rst @@ -73,25 +73,32 @@ Get Started! Ready to contribute? Here's how to set up ``{{ cookiecutter.project_name }}`` for local development. -#. Fork the ``{{ cookiecutter.project_name }}`` repo on GitHub. -#. Clone your fork locally: +#. First, clone the ``{{ cookiecutter.project_name }}`` repo locally. - .. code-block:: console + * If you are not a ``{{ cookiecutter.project_name }}`` collaborator, first fork the ``{{ cookiecutter.project_name }}`` repo on GitHub, then clone your fork locally. + + .. code-block:: console + + git clone git@github.com:your_name_here/{{ cookiecutter.project_name | replace(' ', '-') }}.git - git clone git@github.com:your_name_here/{{ cookiecutter.project_name | replace(' ', '-') }}.git + * If you are a ``{{ cookiecutter.project_name }}`` collaborator, clone the ``{{ cookiecutter.project_name }}`` repo directly. + + .. code-block:: console + + git clone git@github.com:``{{ cookiecutter.github_username }}``/{{ cookiecutter.project_name | replace(' ', '-') }}.git #. Install your local copy into a development environment. {% if cookiecutter.use_conda == 'y' -%} - You can create a new Anaconda development environment with: + You can create a new Anaconda development environment with: .. code-block:: console conda env create -f environment-dev.yml - conda activate {{ cookiecutter.project_slug }} + conda activate {{ cookiecutter.project_slug }}-dev make dev - {%- else -%} + {%- else -%} - Using ``virtualenv`` (``virtualenvwrapper``), you can create a new development environment with: + Using ``virtualenv`` (``virtualenvwrapper``), you can create a new development environment with: .. code-block:: console @@ -99,19 +106,26 @@ Ready to contribute? Here's how to set up ``{{ cookiecutter.project_name }}`` fo mkvirtualenv {{ cookiecutter.project_slug }} cd {{ cookiecutter.project_slug }}/ make dev - {%- endif %} + {%- endif %} + + If you are on Windows, replace the ``make dev`` command with the following: + + .. code-block:: console + + python -m pip install -e .[dev] + pre-commit install - This installs ``{{ cookiecutter.project_slug }}`` in an "editable" state, meaning that changes to the code are immediately seen by the environment. To ensure a consistent coding style, `make dev` also installs the ``pre-commit`` hooks to your local clone. + This installs ``{{ cookiecutter.project_slug }}`` in an "editable" state, meaning that changes to the code are immediately seen by the environment. To ensure a consistent coding style, `make dev` also installs the ``pre-commit`` hooks to your local clone. - On commit, ``pre-commit`` will check that{% if cookiecutter.use_black == 'y' %} ``black``, ``blackdoc``, ``isort``,{% endif %} ``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. + On commit, ``pre-commit`` will check that{% if cookiecutter.use_black == 'y' %} ``black``, ``blackdoc``, ``isort``,{% endif %} ``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: + You can also run the hooks manually with: .. code-block:: console pre-commit run -a - If you want to skip the ``pre-commit`` hooks temporarily, you can pass the `--no-verify` flag to `git commit`. + 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: @@ -119,7 +133,7 @@ Ready to contribute? Here's how to set up ``{{ cookiecutter.project_name }}`` fo 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, we **strongly** suggest running the tests in your environment or with the help of ``tox``: @@ -138,7 +152,7 @@ Ready to contribute? Here's how to set up ``{{ cookiecutter.project_name }}`` fo git commit -m "Your detailed description of your changes." git push origin name-of-your-bugfix-or-feature - If ``pre-commit`` hooks fail, try re-committing your changes (or, if need be, you can skip them with `git commit --no-verify`). + If ``pre-commit`` hooks fail, try fixing the issues, re-staging the files to be committed, and re-committing your changes (or, if need be, you can skip them with `git commit --no-verify`). #. Submit a `Pull Request `_ through the GitHub website. @@ -154,13 +168,33 @@ Ready to contribute? Here's how to set up ``{{ cookiecutter.project_name }}`` fo # To simply test that the docs pass build checks python -m tox -e docs +#. If changes to your branch are made on GitHub, you can update your local branch with: + + .. code-block:: console + + git checkout name-of-your-bugfix-or-feature + git fetch + git pull origin name-of-your-bugfix-or-feature + + If you have merge conflicts, you might need to replace `git pull` with `git merge` and resolve the conflicts manually. + Resolving conflicts from the command line can be tricky. If you are not comfortable with this, you can ignore the last command and instead use a GUI like PyCharm or Visual Studio Code to merge the remote changes and resolve the conflicts. + +#. Before merging, your Pull Request will need to be based on the `main` branch of the ``{{ cookiecutter.project_name }}`` repository. If your branch is not up-to-date with the `main` branch, you can perform similar steps as above to update your branch: + + .. code-block:: console + + git checkout name-of-your-bugfix-or-feature + git fetch + git pull origin main + See the previous step for more information on resolving conflicts. + #. 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 `{{ cookiecutter.project_slug }}` documentation website. - If your branch is not a fork (ie: you are a maintainer), your branch will be automatically deleted. - You will have contributed your first changes to ``{{ cookiecutter.project_slug }}``! + You will have contributed to ``{{ cookiecutter.project_slug }}``! Pull Request Guidelines ----------------------- @@ -169,9 +203,11 @@ Before you submit a pull request, check that it meets these guidelines: #. The pull request should include tests and should aim to provide `code coverage `_ for all new lines of code. You can use the `--cov-report html --cov {{ cookiecutter.project_slug }}` 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 also be updated. Put your new functionality into a function with a docstring, and add the feature to the list in ``README.rst``. +#. All functions should be documented with `docstrings` following the `numpydoc `_ format. + +#. If the pull request adds functionality, either update the documentation or create a new notebook that demonstrates the feature. Library-defining features should also be listed in ``README.rst``. -#. The pull request should work for Python 3.8, 3.9, 3.10, 3.11, 3.12 and PyPy. Check that the tests pass for all supported Python versions. +#. The pull request should work for all currently supported Python versions. Check the `pyproject.toml` or `tox.ini` files for the list of supported versions. Tips ---- diff --git a/{{cookiecutter.project_slug}}/docs/installation.rst b/{{cookiecutter.project_slug}}/docs/installation.rst index 5d4e5371a..dd9275416 100644 --- a/{{cookiecutter.project_slug}}/docs/installation.rst +++ b/{{cookiecutter.project_slug}}/docs/installation.rst @@ -2,6 +2,19 @@ Installation ============ +.. + We strongly recommend installing {{ cookiecutter.project_name }}, in an Anaconda Python environment. Futhermore, due to the complexity of some packages, the default dependency solver can take a long time to resolve the environment. If `mamba` is not already your default solver, consider running the following commands in order to speed up the process: + + .. code-block:: console + + conda install -n base conda-libmamba-solver + conda config --set solver libmamba + +If you don't have `pip`_ installed, this `Python installation guide`_ can guide you through the process. + +.. _pip: https://pip.pypa.io +.. _Python installation guide: http://docs.python-guide.org/en/latest/starting/installation/ + Stable release -------------- @@ -11,12 +24,12 @@ To install {{ cookiecutter.project_name }}, run this command in your terminal: python -m pip install {{ cookiecutter.project_slug }} -This is the preferred method to install {{ cookiecutter.project_name }}, as it will always install the most recent stable release. +.. + .. code-block:: console -If you don't have `pip`_ installed, this `Python installation guide`_ can guide you through the process. + conda install {{ cookiecutter.project_slug }} -.. _pip: https://pip.pypa.io -.. _Python installation guide: http://docs.python-guide.org/en/latest/starting/installation/ +This is the preferred method to install {{ cookiecutter.project_name }}, as it will always install the most recent stable release. From sources @@ -24,20 +37,59 @@ From sources The sources for {{ cookiecutter.project_name }} can be downloaded from the `Github repo <{{ cookiecutter.__gh_slug}}>`_. -You can either clone the public repository: +#. Download the source code from the `Github repo`_ using one of the following methods: -.. code-block:: console + * Clone the public repository: - git clone git@github.com:{{ cookiecutter.github_username }}/{{ cookiecutter.project_name | replace(' ', '_') }}.git + .. code-block:: console -Or download the `tarball <{{ cookiecutter.__gh_slug}}/tarball/main>`_: + git clone git@github.com:{{ cookiecutter.github_username }}/{{ cookiecutter.project_name | replace(' ', '_') }}.git -.. code-block:: console + * Download the `tarball <{{ cookiecutter.__gh_slug}}/tarball/main>`_: - curl -OJL {{ cookiecutter.__gh_slug}}/tarball/main + .. code-block:: console -Once you have a copy of the source, you can install it with: + curl -OJL {{ cookiecutter.__gh_slug}}/tarball/main -.. code-block:: console +#. Once you have a copy of the source, you can install it with: + + .. code-block:: console + + python -m pip install . + + .. + .. code-block:: console + + conda env create -f environment-dev.yml + conda activate {{ cookiecutter.project_slug }}-dev + make dev + + If you are on Windows, replace the ``make dev`` command with the following: + + .. code-block:: console + + python -m pip install -e .[dev] + + Even if you do not intend to contribute to `{{ cookiecutter.project_name }}`, we favor using `environment-dev.yml` over `environment.yml` because it includes additional packages that are used to run all the examples provided in the documentation. + If for some reason you wish to install the `PyPI` version of `{{ cookiecutter.project_name }}` into an existing Anaconda environment (*not recommended if requirements are not met*), only run the last command above. + +#. When new changes are made to the `Github repo`_, if using a clone, you can update your local copy using the following commands from the root of the repository: + + .. code-block:: console + + git fetch + git checkout main + git pull origin main + python -m pip install . + + .. + .. code-block:: console + + git fetch + git checkout main + git pull origin main + conda env update -n {{ cookiecutter.project_slug }}-dev -f environment-dev.yml + conda activate {{ cookiecutter.project_slug }}-dev + make dev - python -m pip install . + These commands should work most of the time, but if big changes are made to the repository, you might need to remove the environment and create it again.