Contribution and Development Guide

Welcome to AlphaPeel contribution and development guide.

This guide will give you an overview of the contribution and development workflow via the AlphaPeel GitHub repository at https://github.com/AlphaGenes/AlphaPeel.

Critically, see also a list of issues at https://github.com/AlphaGenes/AlphaPeel/issues.

Fork the repository

First, you should fork the repository.

For more information, see the GitHub Docs.

Clone your forked repository

Clone your forked repository into a local directory and initialise submodules at the same time by running the following command in your terminal:

git clone --recurse-submodules URL_of_your_forked_repository

Depending on the type of code change, you should use different branches. First, check the available branches:

cd AlphaPeel
git branch # check available branches

Large code changes should go to dedicated development branches, which will be later merged into the devel branch by maintainers:

git checkout devel # start from the development branch
git branch issue_GitHubIssueNumber # work on issue with GitHub number GitHubIssueNumber
git checkout issue_GitHubIssueNumber
# now work on your code changes

It is a good practice that you first open an issue to document what you plan to do, then follow the above process.

Small code changes can go directly to the devel branch, which will eventually be merged into the main branch by maintainers, but check this with the maintainers when you open/discuss the issue:

git checkout devel
# now work on your code changes

Stable code for wider use will be published is in the main branch. While most changes will be happening on the devel branch, critical bugfixes, can go to the main branch, but check this with the maintainers when you open/discuss the issue:

git checkout main
# now work on your code changes

Make changes in your clone

Make changes to the code and commit them to your local clone repository. Adding AlphaGenes/AlphaPeel#GitHubIssueNumber in the message will link the commit with the issue page.

Before you commit the changes, make sure you test your changes by running the tests and examples. To this end, you should install pytest and pytest-benchmark (see pytest Documentation and pytest-benchmark Documentation) and run pytest on the distribution built on your modified code to see if the code passes all the tests.

To install pytest and pytest-benchmark:

pip install pytest
pip install pytest-benchmark

To run pytest:

pytest

If the tests run successfully, you are expected to see output similar to the following:

============================= test session starts ==============================
platform linux -- Python 3.11.14, pytest-9.0.2, pluggy-1.6.0
benchmark: 5.2.3 (defaults: timer=time.perf_counter disable_gc=False min_rounds=5 min_time=0.000005 max_time=1.0 calibration_precision=10 warmup=False warmup_iterations=100000)
rootdir: /home/runner/work/AlphaPeel/AlphaPeel
configfile: pyproject.toml
plugins: benchmark-5.2.3
collected 33 items

tests/accuracy_tests/run_accu_test.py ....................               [ 60%]
tests/functional_tests/run_func_test.py .............                    [100%]
...

The instructions of building your own distribution is available at Install from the git repository.

Instructions on running the examples are at run-examples.

If tests and examples pass, finally install pre-commit and the pre-commit hooks for code formatting.

pip install pre-commit
pre-commit install

Later on, the pre-commit hooks will automatically run on the files you have changed when you commit your changes.

An example output of the pre-commit hooks is as follows:

black....................................................................Passed
flake8...................................................................Passed

For more information, see pre-commit Documentation.

To commit your changes, run the following commands in your terminal:

# after saving your code changes
git status # check which files you have changed
git diff fileThatYouHaveChanged # review changes
git add fileThatYouHaveChanged
git commit -m "Informative short message AlphaGenes/AlphaPeel#GitHubIssueNumber"

In the git add line above, don’t use git add . because this last command will add all changes files to your commit, including temporary files that might not belong in the repository. Are you aware of .gitignore file?

In the git add line above, don’t use git add . because this last command will add all changes files to your commit, including temporary files that might not belong in the repository. Are you aware of <https://git-scm.com/docs/gitignore>_?

Update submodules?

Sometimes you have to update the submodules in line with your code changes in the AlphaPeel or the submodules.

First, check the current state of the submodule:

git submodule status

Next, check the latest commit in the submodule’s remote repository:

cd src/tinypeel/tinyhouse
git log --oneline --max-count=1 origin/main
cd ../../..

If the commit hashes match, then the submodule reference is up to date. If you want to use the old submodule version, then a mismatch is ok. Otherwise, update the reference using:

git submodule update --remote
git commit -m "Updated submodule reference to X.Y.Z AlphaGenes/AlphaPeel#GitHubIssueNumber"
# provide submodules version (X.Y.Z) or commit hash

Create a pull request

Create a pull request (PR) to propose your changes to the repository. Maintainers will review your PR.

Update the version of the package to publish the package

Note

This section is only for the maintainers to publish a new package version.

To release a new package version, we must update the version in pyproject.toml. For example, if the current version of the package is 1.1.3 and the updated version should be 1.1.4, run:

vi pyproject.toml

modify the following:

...
[project]
version = "1.1.3"
...

to

...
[project]
version = "1.1.4"
...

Remember to also update the version number in the test workflow file .github/workflows/tests.yml, which is used to test the distribution built on the modified code:

vi .github/workflows/tests.yml

modify the following:

- name: Install AlphaPeel
    run: pip install dist/alphapeel-1.1.3-py3-none-any.whl

to

- name: Install AlphaPeel
    run: pip install dist/alphapeel-1.1.4-py3-none-any.whl

commit the change:

git commit -m "Bumped version to 1.1.4"

create the release with new version number according to GitHub Docs.

The above will trigger workflow actions to publish the package on PyPI and documentation on Read the Docs:

PyPI

Read the Docs