diff --git a/docs/developer_guide.rst b/docs/developer_guide.rst index 555da6f9..f3fb10dc 100644 --- a/docs/developer_guide.rst +++ b/docs/developer_guide.rst @@ -1,4 +1,232 @@ Developer guide =============== -TOOD \ No newline at end of file +Developer install with Mamba +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +First we need to install a Mamba distribution. There are a few options but here we opt for Miniforge3 as it includes Mamba. + +You can follow the install instructions for `Miniforge3 here `_ or follows the commands below. +Download + +.. code-block:: sh + + curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh" + bash Miniforge3-$(uname)-$(uname -m).sh + +Install Miniforge3 + +.. code-block:: sh + + bash Miniforge3-Linux-x86_64.sh + + +Activate the base environment in your current terminal + +.. code-block:: sh + + mamba activate + + +It is recommended to create a new environment + +.. code-block:: sh + + mamba create --name new_env python=3.11 + + +Activate the new environment + +.. code-block:: sh + + mamba activate new_env + +We have aspirations to create a conda-forge package which will combine these final two steps, but for now FreeCAD and GEOUNED can be installed in two commands. +Install FreeCAD which is the main dependency + +.. code-block:: sh + + mamba install -c conda-forge freecad + +Fork the GEOUNED-org/GEOUNED repository by clicking this link, unchecking the Copy the main branch only check box and clicking create fork + +`https://github.com/GEOUNED-org/GEOUNED/fork `_ + +Assuming that you have `setup `_ and `added `_ SSH keys then we can clone your forked GEOUNED repository. +Replace with your own github username + +.. code-block:: sh + + git clone git@github.com:/GEOUNED.git + +Then change directory into the repository root like this + +.. code-block:: sh + + cd GEOUNED + +Install GEOUNED with pip, we also prefix this with "python -m" to ensure that pip install uses the correct Python interpreter. +We are also adding the -e to get an editable install so that when you make local changes to the repo these are picked up in your Python scripts straight away (without needing to reinstall). +We also include all the optional dependencies so that we can run tests locally and build the docs locally. + +.. code-block:: sh + + python -m pip install -e .[tests,docs] + +Then you will be able to run import GEOUNED from within Python + +.. code-block:: python + + import geouned + +You will also be able to use the GEOUNED command line tool + +.. code-block:: bash + + geouned_cadtocsg --help + +Checkout feature branches from dev and make local changes on you own branch + +.. code-block:: sh + + git checkout dev + git checkout -b 'my_new_feature' + +Pull requests are welcome + +Building the docs locally +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: sh + + python -m pip install -e .[docs] + sphinx-build docs _build + +Then view the docs by opening the _build/index.html file in a web browser. + +When the CI builds docs it puts the latest stable version in the _build directory on the gh-pages branch. + +Versions (including dev) are built and put in subdirectories of the _build directory on the gh-pages branch. + +Running the tests locally +~~~~~~~~~~~~~~~~~~~~~~~~~ + +As we installed the tests dependencies using the [tests] option the we can run the tests locally with pytest. + + +.. code-block:: sh + + python -m pip install -e .[tests,docs] + +However we need one more dependency to run the tests. + +.. code-block:: sh + + mamba install -c conda-forge openmc + +Then we can run the tests with the following command from the root of the repository. + +.. code-block:: sh + python -m pytest + +We can run individual test files by specifying the file path + +.. code-block:: sh + python -m pytest tests/test_convert.py + +We can run individual test functions by specifying the file path and function name + +.. code-block:: sh + python -m pytest tests/test_convert.py -k 'test_conversion' + +Additional pytest options that might be useful are including -s for standard output and -vv for very verbose output. + +.. code-block:: sh + + python -m pytest -s -vv + +Merging a pull requests +~~~~~~~~~~~~~~~~~~~~~~~ + +Pull requests should be made from feature branches on a fork of the repository to the dev branch. + +Tests checking the code will run automatically on the pull request. + +If the tests pass and at least one approver approves then the pull request can be merged. + +When a pull request is ready to be merged then the pull request should be **squashed** and merged into the dev branch. + +Releasing a new version +~~~~~~~~~~~~~~~~~~~~~~~ + +To release a new version we first need to add and entry to the docs/version_switcher.json file on the dev branch + +.. code-block:: python + + [ + { + "name": "dev", + "version": "dev", + "url": "https://geouned-org.github.io/GEOUNED/dev" + }, + { + "name": "1.1.0", + "version": "1.1.0", + "url": "https://geouned-org.github.io/GEOUNED/1.1.0" + } + ] + +For example adding version 1.2.3 would look like this + +.. code-block:: python + + [ + { + "name": "dev", + "version": "dev", + "url": "https://geouned-org.github.io/GEOUNED/dev" + }, + { + "name": "1.1.0", + "version": "1.1.0", + "url": "https://geouned-org.github.io/GEOUNED/1.1.0" + }, + { + "name": "1.2.3", + "version": "1.2.3", + "url": "https://geouned-org.github.io/GEOUNED/1.2.3" + } + ] + +Then create a `pull request from dev branch to main branch `_ + +Once the tests for this pass then merge the pull request in. **Do not squash** this pull request as we want to keep the history of the version changes. + +Then `create a new release on the main branch `_ with the version number and a description of the changes. + +Create a new tag with the version number (e.g. 1.2.3) and the release name (e.g. v1.2.3) and the release description. + +Press the Generate release notes button to get the release notes from the pull request descriptions. + +Then press the Publish release button to create the release. + +This will create the release and trigger github actions for +- publishing the PyPI package +- building the docs and setting the default docs to the new version + +Check the actions both pass by going to the `actions tab https://github.com/shimwell/GEOUNED/actions>`_ on the repository and checking the latest actions. + +Conda Forge Releasing +~~~~~~~~~~~~~~~~~~~~~ + +The conda-forge package release is done after the PyPI release. This is because the conda-forge package is built from the PyPI package. + +Conda Forge has a bot thew generates a pull request to update the conda-forge recipe. This is done automatically when the PyPI package is released. + +The pull request will be generated in the `conda-forge/GEOUNED-feedstock `_ repository. + +Check the pull request and if the tests pass then merge the pull request. + +A Conda Forge package will be built and released to the conda-forge channel. + +Once released the package will be visaible on the `conda-forge channel `_. diff --git a/docs/install/install_linux.rst b/docs/install/install_linux.rst index 30822452..1353c82b 100644 --- a/docs/install/install_linux.rst +++ b/docs/install/install_linux.rst @@ -118,99 +118,6 @@ You will also be able to use the GEOUNED command line tool geouned_cadtocsg --help -Developer install with Mamba -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -First we need to install a Mamba distribution. There are a few options but here we opt for Miniforge3 as it includes Mamba. - -You can follow the install instructions for `Miniforge3 here `_ or follows the commands below. -Download - -.. code-block:: sh - - curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh" - bash Miniforge3-$(uname)-$(uname -m).sh - -Install Miniforge3 - -.. code-block:: sh - - bash Miniforge3-Linux-x86_64.sh - - -Activate the base environment in your current terminal - -.. code-block:: sh - - mamba activate - - -It is recommended to create a new environment - -.. code-block:: sh - - mamba create --name new_env python=3.11 - - -Activate the new environment - -.. code-block:: sh - - mamba activate new_env - -We have aspirations to create a conda-forge package which will combine these final two steps, but for now FreeCAD and GEOUNED can be installed in two commands. -Install FreeCAD which is the main dependency - -.. code-block:: sh - - mamba install -c conda-forge freecad - -Fork the GEOUNED-org/GEOUNED repository by clicking this link, unchecking the Copy the main branch only check box and clicking create fork - -`https://github.com/GEOUNED-org/GEOUNED/fork `_ - -Assuming that you have `setup `_ and `added `_ SSH keys then we can clone your forked GEOUNED repository. -Replace with your own github username - -.. code-block:: sh - - git clone git@github.com:/GEOUNED.git - -Then change directory into the repository root like this - -.. code-block:: sh - - cd GEOUNED - -Install GEOUNED with pip, we also prefix this with "python -m" to ensure that pip install uses the correct Python interpreter. -We are also adding the -e to get an editable install so that when you make local changes to the repo these are picked up in your Python scripts straight away (without needing to reinstall). -We also include all the optional dependencies so that we can run tests locally and build the docs locally. - -.. code-block:: sh - - python -m pip install -e .[tests,docs] - -Then you will be able to run import GEOUNED from within Python - -.. code-block:: python - - import geouned - -You will also be able to use the GEOUNED command line tool - -.. code-block:: bash - - geouned_cadtocsg --help - -Checkout feature branches from dev and make local changes on you own branch - -.. code-block:: sh - - git checkout dev - git checkout -b 'my_new_feature' - -Pull requests are welcome - .. Apt-get .. ~~~~~~~