Contributing to Asynch

You are here to help on Asynch? Awesome, feel welcome and read the following sections in order to know what and how to work on something. If you get stuck at any point you can create a ticket on GitHub.

Contributing to development

If you want to deep dive and help out with development on Read the Docs, then first get the project installed locally according to the Installation instruction. After that is done we suggest you have a look at tickets in our issue tracker that are labelled Good First Bug. These are meant to be a great way to get a smooth start and won’t put you in front of the most complex parts of the system.

If you are up to more challenging tasks with a bigger scope, then there are a set of tickets with a Enhancement tag. These tickets have a general overview and description of the work required to finish. If you want to start somewhere, this would be a good place to start. That said, these aren’t necessarily the easiest tickets. They are simply things that are explained. If you still didn’t find something to work on, search for the Sprintable label. Those tickets are meant to be standalone and can be worked on ad-hoc.

When contributing code, then please follow the standard Contribution Guidelines set forth at contribution-guide.org.

Keeping the documentation updated

When a change affects users (input formats, models, global file options, the Python package, …), update the documentation in the same commit, and record the change in CHANGELOG.md.

Documentation structure

The documentation lives in docs/ and is built with Sphinx:

  • docs/guide/*.md: the guide (Markdown, read by MyST; it also reads well on GitHub);

  • docs/*.rst: the reference manual (reStructuredText);

  • the Python API pages are generated from the docstrings of python/asynch (autodoc), and the C API pages from the comments of src/asynch_interface.h, src/asynch_api.h and src/models/model.h (Doxygen and breathe);

  • docs/conf.py is the configuration; docs/index.md the home page and table of contents.

Working locally

python3 -m venv ~/docs-venv
~/docs-venv/bin/pip install -r docs/requirements.txt
sudo apt-get install doxygen                 # optional: without it the C API pages show a note
~/docs-venv/bin/sphinx-build -b html docs docs/_build/html

Open docs/_build/html/index.html in a browser.

Publishing

The GitHub Actions workflow .github/workflows/docs.yml builds the documentation on every push and publishes it with GitHub Pages. It needs, once, Settings > Pages > Source: GitHub Actions in the repository.

Managing releases

Versions follow semantic versioning: x.y.z. To release version x.y.z:

  1. Set the version in configure.ac (AC_INIT([asynch], [x.y.z], ...)), python/pyproject.toml and python/asynch/__init__.py (__version__).

  2. In CHANGELOG.md, rename the section [Unreleased] to [x.y.z] - YYYY-MM-DD, with a short summary of the version at its top, and start a new empty [Unreleased] section. Add the version to Releases Notes: what changes for a user, breaking changes first.

  3. Build and run make check (9. Reproducibility and regression testing); compare the examples with the previous version with tests/regression/run_examples.py --compare-to.

  4. Commit and push, then create the tag, in either of two ways:

    • from the command line:

      git tag -a vx.y.z -m "ASYNCH x.y.z"
git push origin vx.y.z

    • or on GitHub: Actions > Release > Run workflow, choose the branch and type the version x.y.z; the tag is created on the latest commit of that branch, after it has been built and tested.

The workflow .github/workflows/release.yml then checks that the tag matches configure.ac, builds ASYNCH, runs make check, and publishes the GitHub release. Its description is the first paragraph of the version in CHANGELOG.md, with links to the changelog and the release notes. Write that paragraph as a general summary of the version; the details belong in the entries below it. Three files are attached:

  • asynch-x.y.z.tar.gz, made by make dist: the sources with a ready configure script, which build without autotools (./configure && make && make check);

  • the Python package as a wheel (it uses the libasynch.so built from the sources);

  • the documentation website as a zip file, to read offline.

Publishing on PyPI

The job pypi of .github/workflows/release.yml also uploads the ready-made wheel to PyPI, as the project asynch-hlm (the name asynch belongs to another project there; the package is still imported as asynch). It uses Trusted Publishing: PyPI accepts uploads from this workflow of this repository, so no password or token is stored in GitHub. To set it up, once:

  1. Create an account on https://pypi.org (with two-factor authentication, which PyPI requires).

  2. In Your account > Publishing > Add a new pending publisher, choose GitHub and enter: PyPI project name asynch-hlm, owner gurbuzf, repository asynch, workflow release.yml, environment pypi.

From the Actions tab (Release > Run workflow), the wheel goes to PyPI when Publish on PyPI is ticked (the default). For a release started by pushing a tag, set the repository variable PUBLISH_TO_PYPI to true (Settings > Secrets and variables > Actions > Variables). To upload the wheel of a release that already exists (for instance made before PyPI was set up), run the workflow with its version and tick Only upload an existing release to PyPI: nothing is built, and the release is not changed.

Users install the latest version with pip install asynch-hlm (no version or file name to type), a given version with pip install asynch-hlm==x.y.z. A version number can be uploaded to PyPI only once: a release that must be redone needs a new version.

The description on the PyPI page is python/README.md followed by a Changelog section that python/setup.py makes from CHANGELOG.md when the wheel is built: the first paragraph of each released version ([Unreleased] is left out). Keep that paragraph general, short and readable on its own. The page also links to the full changelog and to the release notes.