Developer guide#

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.

Conda could be used instead of Mamba but Mamba is faster and more reliable. If you don’t have permission to install Miniforge3 then you could try using Conda instead. For you could install mamba into conda with.

conda install -c conda-forge mamba -y

You can follow the install instructions for Miniforge3 here or follows the commands below. Download

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

bash Miniforge3-Linux-x86_64.sh

Activate the base environment in your current terminal

mamba activate

It is recommended to create a new environment

mamba create --name new_env python=3.11

Activate the new environment

mamba activate new_env

As our main dependency FreeCAD is not available on PYPi but we can install it from conda-forge.

mamba install -c conda-forge freecad -y

To be able to run test cases and stochastic volume calculation, it is needed to install openmc and pytest from conda-forge.

mamba install -c conda-forge pytest openmc

Fork the GEOUNED-org/GEOUNED repository by clicking this link, unchecking the Copy the main branch only check box and clicking create fork

GEOUNED-org/GEOUNED

Assuming that you have setup and added SSH keys then we can clone your forked GEOUNED repository. Replace <USER> with your own github username

git clone git@github.com:<USER>/GEOUNED.git

Then change directory into the repository root like this

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.

python -m pip install -e .[tests,docs]

Then you will be able to run import GEOUNED from within Python

import geouned

You will also be able to use the GEOUNED command line tool

geouned_cadtocsg --help

Checkout feature branches from dev and make local changes on you own branch

git checkout dev
git checkout -b 'my_new_feature'

Pull requests are welcome

Building the docs locally#

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.

python -m pip install -e .[tests,docs]

However we need one more dependency to run the tests.

mamba install -c conda-forge openmc -y

Then we can run the tests with the following command from the root of the repository.

python -m pytest

We can run individual test files by specifying the file path

python -m pytest tests/test_convert.py

We can run individual test functions by specifying the file path and function name

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.

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

[
    {
        "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

[
    {
        "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.

Version Numbering#

GEOUNED will use Semantic Versioning to number releases of the tool, in the form “Major.Minor.Patch”, e.g., “3.15.9”.

On this page
Show Source