From 559bc12ee1207859f3fc3d26afb9d4272d6822c3 Mon Sep 17 00:00:00 2001 From: RemDelaporteMathurin Date: Wed, 24 Jun 2026 16:37:59 -0400 Subject: [PATCH 1/3] changes to contributing guide --- docs/source/devguide/index.rst | 279 ++++++++++++++++++++------------- 1 file changed, 166 insertions(+), 113 deletions(-) diff --git a/docs/source/devguide/index.rst b/docs/source/devguide/index.rst index 92b594243..371b48a2d 100644 --- a/docs/source/devguide/index.rst +++ b/docs/source/devguide/index.rst @@ -4,261 +4,314 @@ Contributing ================= +All contributions are welcome, no matter how small. +Whether you are fixing a typo, reporting a bug, or implementing a new feature, your help is appreciated. + ------------------ -How to contribute? +Ways to contribute ------------------ -All contributions, even the smallest, are welcome! -There are many ways to contribute to FESTIM. - -Be active in the community by: +**In the community:** -* Reporting a bug -* Proposing a feature +* `Report a bug `_ +* `Propose a feature `_ -And/or contribute to the source code by: +**In the codebase:** -* Improving the documentation -* Fixing bugs -* Implementing new features +* Improve the documentation +* Fix bugs +* Implement new features ------------------------ Contributing to the code ------------------------ -For complete information on contributions with GitHub see this guide on `GitHub `_. +For a general overview of contributing to GitHub projects, see the +`GitHub contributing guide `_. .. tip:: - If you're a beginner, look for `issues tagged with "Good first issue" `_. - - These issues are usually relatively easy to tackle and perfect for newcomers. + If you are new to the project, look for + `issues tagged "good first issue" `_. + These are typically straightforward and a great way to get started. #. `Fork the repository `_ - By forking the repository, you create a copy where you can safely make changes. + Forking creates a personal copy of the repository where you can freely make changes. -#. Clone your fork +#. Clone your fork and add the upstream remote .. code-block:: bash git clone https://github.com/[your_username]/FESTIM + cd FESTIM + git remote add upstream https://github.com/festim-dev/FESTIM + + Replace ``[your_username]`` with your GitHub username. + The upstream remote lets you pull in changes from the main repository to keep your fork up to date: + + .. code-block:: bash + + git fetch upstream + git merge upstream/main + +#. Create a branch + + Always work on a dedicated branch rather than directly on ``main``: + + .. code-block:: bash + + git checkout -b my-feature-branch + +#. Set up your development environment + + Create a dedicated conda environment and install FESTIM from conda-forge. + This pulls in all required dependencies, including FEniCSx: + + .. code-block:: bash + + conda create -n festim-dev + conda activate festim-dev + conda install -c conda-forge festim - Remember to replace ``[your_username]`` with your GitHub username. + Then uninstall the conda-managed FESTIM package and replace it with your + local clone in editable mode, so that any changes you make are picked up + immediately without reinstalling: + + .. code-block:: bash + + pip uninstall festim + pip install -e . + + .. note:: + + The ``-e`` flag installs the package in *editable* mode. + Python will import directly from your local source tree, + meaning you do not need to reinstall after each change. #. Make your changes - Commit your changes locally and push them to your fork. + Commit your changes with a clear, descriptive message: .. code-block:: bash git add [modified files] - git commit -m "Your commit message" - git push + git commit -m "Short description of the change" + git push origin my-feature-branch #. Test your code - If you are adding new features or fixing bugs, it is important to test your code. + Before opening a PR, run the test suite locally to make sure nothing is broken. See :ref:`Test suite` for more information. -#. Format your code using `Black `_. +#. Format your code - The source code of FESTIM is formated with the Black code formatter. Using of a unified code style simplifies the code review - and increases its readability. See :ref:`Code formatting` for more information. + FESTIM uses `Black `_ for consistent code formatting. + See :ref:`Code formatting` for more information. -#. Optional: Build the documentation +#. Optional: build the documentation - You may want to build the documentation to see if your changes are correctly reflected or if you are updating the docs. + If you modified or added documentation, build it locally to verify it renders correctly. See :ref:`Documentation guide` for more information. #. `Open a PR `_ -#. Wait for a :ref:`maintainer` to review your PR + Include a clear description of what the PR does and reference any related issues + (e.g. ``Closes #123``). + +#. Wait for a :ref:`maintainer ` to review your PR - Before merging your changes, they have to be reviewed. We ensure the changes don't break anything during the review and eventually propose/request improvements. - The time before the review will depend on the maintainers' availability. + Maintainers will review your changes to ensure correctness and code quality, and may + request further modifications. Review time depends on maintainer availability. -#. When everything is in order, the maintainers will merge your PR! +#. Once approved, a maintainer will merge your PR. Congratulations! ----------- Maintainers ----------- -The maintainers are the people who have the right to merge PRs to the repository. -They consist of the following individuals: +Maintainers are the people with merge rights on the repository: -- Remi Delaporte-Mathurin (`@RemDelaporteMathurin `_) +- Remi Delaporte-Mathurin (`@RemDelaporteMathurin `_) -- project lead - James Dark (`@jhdark `_) - Vladimir Kulagin (`@KulaginVladimir `_) -The project lead is Remi Delaporte-Mathurin. - ---------- Test suite ---------- -FESTIM uses continuous integration (CI) to ensure code quality and eliminate as many bugs as possible. - -In a nutshell, every time a change is pushed to the repository (or to a PR), a suite of tests is automatically triggered. -This is to make sure the changes don't break existing functionalities. -It is also very useful to catch bugs that developers could have missed. -Click `here `_ for more information on CI. +FESTIM uses continuous integration (CI) to maintain code quality. +Every push to the repository or a pull request triggers the test suite automatically, +catching regressions and bugs early. +See `Atlassian's CI guide `_ +for a general introduction to CI. -All the tests can be found in the `test folder `_ at the root of the FESTIM repository. - -You need to have the right dependencies installed to test your code (see :ref:`installation`). +All tests live in the `test folder `_ +at the root of the repository. .. note:: - Make sure to install ``pytest`` to run the test suite locally: + Install ``pytest`` if you haven't already: .. code-block:: bash pip install pytest - And then run the tests using: + Then run the full test suite from the project root: .. code-block:: bash pytest test/ - -Whenever contributors open a PR, **the tests must pass** in order for the PR to be merged in. -In some cases, new tests need to be written to account for more use cases or to catch bugs that weren't previously caught. +**The tests must pass before a PR can be merged.** + +When fixing a bug or adding a feature, please add or update tests to cover the new behaviour. --------- Debugging --------- -When you find a bug in the code, there are several steps to follow to make things easier for maintainers. +When you find a bug, follow these steps to make things easier for maintainers: + +#. `Raise an issue `_ + + Opening an issue creates a record of the bug and gives maintainers and contributors + a place to troubleshoot, discuss potential fixes, and document workarounds. -#. | `Raise an issue `_ - | - | This is important to keep track of things. - | The issue is a place to talk about the bug, troubleshoot users and sometimes find workarounds. - | It also greatly helps maintainers find the origin of the bug to fix it faster. +#. Write a test that reproduces the bug -#. | Write a test - | To make the test suite more robust, first write a test that catches the bug. - | This may appear useless, but it will help the future contributors by alerting them if they reproduce this error. - | It will also be useful to prove your fix is effective. + A failing test is the clearest way to demonstrate a bug and verify that your fix works. + It also guards against the same bug reappearing in the future. -#. Make your changes and open a PR. +#. Fix the bug and open a PR. -------------------------- Implementing a new feature -------------------------- -#. | `Raise an issue `_ - | - | Before spending time implementing a new great feature, it is better to open an issue first to discuss with the maintainers. - | For all you know, someone is already working at implementing it and all your time would be spent for nothing. - | - | It is also beneficial to discuss with the community on how this new feature would be used. +#. `Raise an issue `_ -#. :ref:`Make your changes`. Don't forget to :ref:`adapt the documentation ` if necessary. + Before writing any code, open an issue to discuss the feature with the maintainers. + Someone may already be working on it, or the maintainers may have context that + shapes the design. -#. Write a test to test your feature +#. :ref:`Make your changes ` and + :ref:`update the documentation ` if needed. -#. Open a PR +#. Write tests to cover the new feature. +#. Open a PR. ---------------- Code formatting ---------------- -Before merging your PR, the modified scripts should be formatted to maintain the consistency of the coding style. FESTIM is formatted using -`Black `_. To install Black, run the following command: +FESTIM uses `Black `_ to enforce a consistent code style, +which reduces noise in code reviews and keeps the codebase readable. + +Install Black: .. code-block:: bash pip install black -After the installation, you can format a file using: +Format a single file: .. code-block:: bash black my_script.py -Alternatively, you can format all files in the current directory with: +Format all files in the current directory: .. code-block:: bash black . +Check formatting without modifying any files: + +.. code-block:: bash -If you use Visual Studio Code, you can install the `extension `_ -with support for the Black formatter. Then, you can set Black as a default formatter for python and enable formatting "on save" for your code. + black --check . + +.. tip:: + + If you use Visual Studio Code, install the + `Black Formatter extension `_ + and enable **Format on Save** to apply Black automatically whenever you save a file. ------------------- Documentation guide ------------------- -The documentation is a crucial part of the project. It is the first thing users will see when they want to use FESTIM. -It is important to keep it up to date and clear. +The documentation is often the first thing a user encounters. +Keeping it accurate, clear, and up to date is as important as keeping the code correct. -The documentation is written in `reStructuredText `_ and is located in the `docs folder `_ at the root of the FESTIM repository. +The docs are written in +`reStructuredText `_ +and live in the `docs folder `_. +They are built with `Sphinx `_ and hosted on +`Read the Docs `_, which rebuilds automatically on every +commit and pull request. -The documentation is built using `Sphinx `_. +**Setting up the documentation environment** -To build the documentation locally, you can use the following command: +.. note:: -.. code-block:: bash + Create a dedicated conda environment with all documentation dependencies: - cd docs/source - make html + .. code-block:: bash + + conda env create -f docs/environment.yml + conda activate festim2-docs -This will generate the documentation in the `docs/source/_build/html` folder. -You can then open the `index.html` file in your browser to see the documentation. -To remove everything and start from scratch, you can use the following command: +**Building the docs** + +From the ``docs/source`` directory: .. code-block:: bash - make clean + cd docs/source + make html -Alternatively, you can use the following command to build the documentation in one line: +Or from the ``docs`` directory in a single step: .. code-block:: bash cd docs sphinx-build -b html source build -.. note:: - - Make sure to have the right dependencies installed. You can create a new conda environment with the following command: +The generated HTML will be in ``docs/source/_build/html``. +Open ``index.html`` in your browser to preview the result. - .. code-block:: bash - - conda env create -f docs/environment.yml - - This will create a new environment called `festim2-docs` with all the necessary dependencies. - Activate it using: - - .. code-block:: bash +To remove all build artefacts and start from scratch: - conda activate festim2-docs - -The documentation is hosted on `Read the Docs `_ and is automatically updated when a new commit is pushed to the repository or to a Pull Request. - -.. note:: +.. code-block:: bash - The documentation is built using the `sphinx_book_theme `_ theme. + cd docs/source + make clean -When contributing to the documentation, make sure to: +**Running doctests** -#. Write clear and concise documentation -#. Use the right syntax -#. Update the documentation when new features are added -#. Test the documentation using: +Verify that all code examples in the documentation execute correctly: .. code-block:: bash cd docs/source make doctest -or using: +Or equivalently: .. code-block:: bash cd docs - sphinx-build -b doctest source build \ No newline at end of file + sphinx-build -b doctest source build + +**Documentation checklist** + +When contributing to the documentation, make sure to: + +* Write clearly and concisely +* Use correct reStructuredText syntax +* Update existing pages when behaviour changes +* Add documentation for any new features +* Run the doctests to confirm all code examples are correct \ No newline at end of file From 26bf966bc3fc3e3dd3eee182a469ae020eb7dc44 Mon Sep 17 00:00:00 2001 From: RemDelaporteMathurin Date: Wed, 24 Jun 2026 16:50:52 -0400 Subject: [PATCH 2/3] miniconda latest --- .readthedocs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 99c829ef2..7237c69c6 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -11,7 +11,7 @@ conda: build: os: "ubuntu-lts-latest" tools: - python: "mambaforge-4.10" + python: "miniconda-latest" # Build documentation in the docs/ directory with Sphinx sphinx: From 6d7ee1e6f86312860b5a4d929550112af54b39bb Mon Sep 17 00:00:00 2001 From: RemDelaporteMathurin Date: Thu, 25 Jun 2026 08:11:48 -0400 Subject: [PATCH 3/3] ubuntu-24.4 --- .readthedocs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 7237c69c6..9cfd850e3 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -9,7 +9,7 @@ conda: environment: docs/environment.yml build: - os: "ubuntu-lts-latest" + os: "ubuntu-24.04" tools: python: "miniconda-latest"