eit_dash developer documentation

If you're looking for user documentation, go here.

Contributions

We welcome all contributions to this open-source project, as long as they follow our code of conduct. We appreciate it if you adhere to our naming and style conventions below.

Please follow these steps:

1. (important) announce your plan to the rest of the community before you start working. This announcement should be in the form of a (new) issue;
2. (important) wait until some kind of consensus is reached about your idea being a good idea;
3. if needed, fork the repository to your own Github profile and create your own feature branch off of the latest master commit. While working on your feature branch, make sure to stay up to date with the master branch by pulling in changes, possibly from the 'upstream' repository (follow the instructions here and here);
4. make sure the existing tests still work by running pytest (see also here);
5. add your own tests (if necessary);
6. update or expand the documentation;
7. update the CHANGELOG.md file with change;
8. push your feature branch to (your fork of) the eit_dash repository on GitHub;
9. create the pull request, e.g. following the instructions here.

In case you feel like you've made a valuable contribution, but you don't know how to write or run tests for it, or how to generate the documentation: don't let this discourage you from making the pull request; we can help you! Just go ahead and submit the pull request, but keep in mind that you might be asked to append additional commits to your pull request.

Conventions

Readability vs complexity/correctness

While we implement "best practices" as much as possible, it is important to state that sometimes readibility or simplicity is more important than absolute correctness. It is hard to define the precise balance we are looking for, so instead we will refer to the Zen of python.

Note that all contrubtions to this project will be published under our Apache 2.0 licence.

Docstrings

We use the google convention for writing docstrings.

Code formatting

We use the Black formatter to format code. If you use Visual Studio Code, the extension by Microsoft is a good place to start. This extension is currently in preview, but seems to work more reliably than older implementations.

Branch naming convention

Please try to adhere to the following branch naming convention: . E.g., 042_life_universe_everything_douglasadams.

This allows, at a single glance, to see in the issue that you're addressing, a hint of what the issue is, and who you are. Also, it simplifies tab autocompletion when switching to your branch.

PR naming convention

Please use an angular convention type, followed by a semicolon and then a description when creating a PR. E.g., feat: added module to calculate the answer to life, the universe, and everything.

Creating a PR

Branching strategy

We use a workflow where main always contains the latest stable release version of eit_dash and where develop contains the next release version under construction.

When creating a new feature, one should branch from develop. When a feature is finished, a PR to pull the feature into develop should be created. After one or multiple features have been pulled into develop, the release workflow can be triggered to automatically create the new feature (minor) release originating from develop.

For bug fixes that can't wait on a feature release, one should branch from main. When the bug fix is finished, the release workflow can be triggered originating from the created branch, usually with a patch update.

In principle, no releases should originate from branches other than develop and bug fix branches.

Code review and continuous integration

All contributions to the project are subject to code review and require at least one approving review before they can be merged onto the main branch.

We have set up continuous integration for linting and testing, among other things. Please ensure that all checks pass before requesting code review.

Please create a "draft PR" until your work is ready for review, as this will avoid triggering the CI prematurely (which uses unnecessary computing power, see here).

You can run the tests and linter locally before activating the CI.

Testing locally

Make sure you have developer options installed by running: poetry install --with test on the repository folder in your environment.

For testing all you need to do is run:

shell poetry run pytest -v tests/unit_tests

Linting and Formatting

We use ruff for linting, sorting imports and formatting of python (notebook) files. The configurations of ruff are set in pyproject.toml file.

If you are using VS code, please install and activate the Ruff extension to automatically format and check linting.

Otherwise, please ensure check both linting (ruff fix .) and formatting (ruff format .) before requesting a review.

We use prettier for formatting most other files. If you are editing or adding non-python files and using VS code, the Prettier extension can be installed to auto-format these files as well.

Making a release

Automated release workflow:

1. IMP0RTANT: Create a PR for the release branch (usually develop) and make sure that all checks pass!
   • if everything goes well, this PR will automatically be closed after the draft release is created.
2. Navigate to Draft Github Release on the Actions tab.
3. On the right hand side, you can select the level increase ("patch", "minor", or "major") and which branch to release from.
   • Follow semantic versioning conventions to choose the level increase:
     • patch: when backward compatible bug fixes were made
     • minor: when functionality was added in a backward compatible manner
     • major: when API-incompatible changes have been made
   • If the release branch is not develop, the workflow will attempt to merge the changes into develop as well. If successful, the release branch will be deleted from the remote repository.
   • Note that you cannot release from main (the default shown) using the automated workflow. To release from main directly, you must create the release manually.
4. Visit Actions tab to check whether everything went as expected.
5. Navigate to the Releases tab and click on the newest draft release that was just generated.
6. Click on the edit (pencil) icon on the right side of the draft release.
7. Check/adapt the release notes and make sure that everything is as expected.
8. Check that "Set as the latest release is checked".
9. Click green "Publish Release" button to convert the draft to a published release on GitHub.
   • This will automatically trigger another GitHub workflow that will take care of publishing the package on PyPi.

Updating the token:

NOTE: the current token (associated to @wbaccinelli) allowing to bypass branch protection will expire on July 7th, 2025. To update the token do the following:

1. Create a personal access token from a GitHub user account with admin priviliges for this repo.
2. Check all the "repo" boxes and the "workflow" box, set an expiration date, and give the token a note.
3. Click green "Generate token" button on the bottom
4. Copy the token immediately, as it will not be visible again later.
5. Navigate to the secrets settings.
6. Edit the GH_PAT key giving your access token as the new value.

Manually create a release:

1. Make sure you have all required developers tools installed pip install -e .'[dev]'.
2. Create a release branch from main and merge the changes into this branch.
   • Ensure that the release branch is ready to be merged back into main (e.g., removing the unnecessary files, fix minor bugs if necessary).
   • Also see our branching strategy above.
3. Ensure all tests pass pytest -v and that linting (ruff check) and formatting (ruff format --check) conventions are adhered to.
4. Bump the version using bump-my-version: bump-my-version bump <level> where level must be one of the following (following semantic versioning conventions):
   • major: when API-incompatible changes have been made
   • minor: when functionality was added in a backward compatible manner
   • patch: when backward compatible bug fixes were made
5. Merge the release branch into main and develop.
6. On the Releases page:
   1. Click "Draft a new release"
   2. By convention, use v<version number> as both the release title and as a tag for the release.
   3. Click "Generate release notes" to automatically load release notes from merged PRs since the last release.
   4. Adjust the notes as required.
   5. Ensure that "Set as latest release" is checked and that both other boxes are unchecked.
   6. Hit "Publish release".
      • This will automatically trigger a GitHub workflow that will take care of publishing the package on PyPi.