Contributing

Version control

We use Git for version control. The code is hosted on GitHub.

How to fork pyDOMCFG, create a branch, and commit your code:

Go to pyDOMCFG and click the Fork button.
Clone your fork and connect the repository to the upstream repository:

git clone https://github.com/your-user-name/pyDOMCFG.git
cd pyDOMCFG
git remote add upstream https://github.com/pyNEMO/pyDOMCFG.git

Create a branch:

git checkout -b name-of-the-branch

Note

Members of @pyNEMO/pydomcfg can create a branch directly from main:

git clone https://github.com/pyNEMO/pyDOMCFG.git
cd pyDOMCFG
git checkout -b name-of-the-branch

This is particularly useful for long-running branches (e.g., develop, stable, …).

To update this branch retrieving changes from the main branch:

git fetch upstream
git merge upstream/main

Once you have made changes, commit your code:

# To check changes:
git status

# If you have created new files:
git add path/to/file-to-be-added

# Commit changes:
git commit -m "short message describing changes"

Push your commits:

git push origin name-of-the-branch

Navigate to your repository on GitHub (https://github.com/your-user-name/pyDOMCFG), click on the Pull Request button, edit title and description, and click Send Pull Request.

Documentation

The documentation consists of two parts: the docstrings in the code itself and the docs in this folder pyDOMCFG/docs/.
The documentation is written in reStructuredText and built using Sphinx.
The docstrings follow the Numpy Docstring Standard.

How to build the documentation:

# Create and activate the docs environment
conda env create -f pyDOMCFG/ci/docs.yml
conda activate pydomcfg_docs

# Navigate to the docs directory
cd pyDOMCFG/docs/

# If you want to do a full clean build
make clean

# Build the documentation
make html

Tests

All tests go into this folder pyDOMCFG/pydomcfg/tests.
We are using pytest for testing.

Test functions should look like this:

def add_one(x):
    return x + 1


def test_add_one():
    expected = 2
    actual = add_one(1)
    assert expected == actual

How to run the tests:

# Create and activate the test environment
conda env create -f pyDOMCFG/ci/environment.yml
conda activate pydomcfg_test

# Navigate to the root directory, install, and run pytest
cd pyDOMCFG
pip install -e .
pytest

Pre-commit formatting

We are using several tools to ensure that code and docs are well formatted:

isort for standardized order in imports.
Black for standardized code formatting.
blackdoc for standardized code formatting in documentation.
Flake8 for general code quality.
Darglint for docstring quality.
mypy for static type checking on type hints.
doc8 for reStructuredText documentation quality.

Setup pre-commit hooks to automatically run all the above tools every time you make a git commit:

# Install the pre-commit package manager.
conda install -c conda-forge pre-commit

# Set up the git hook scripts.
cd pyDOMCFG
pre-commit install

# Now pre-commit will run automatically on the changed files on ``git commit``
# Alternatively, you can manually run all the hooks with:
pre-commit run --all

# You can skip the pre-commit checks with:
git commit --no-verify