Contribute to flowchem

There are many ways of contributing to flowchem: if you are using it and have suggestions or bugs report them in the issue tracker on GitHub, if you find the documentation not clear, propose a change and if you want to add support for new device, that would be awesome as well!

Repository structure

The repository is structured as follows:

  • docs - documentation

  • examples - example of use

  • src - source code

  • tests - test files (pytest) We follow the “src-layout”, read this article for more details.

Moreover, the source code in the flowchem packages is organized in:

  • components - the abstract components representing specific device capabilities (e.g. pumping).

  • devices - containing the code to control the different devices, sorted by manufacturer

  • server - the modules related to configuration parsing and API server initialization.

  • utils - various helper functions

Development process

  1. If you are a first-time contributor:

    • Go to flowchem gitHub repository and click the “fork” button to create your own copy of the project.

    • Clone the project to your local computer: git clone https://github.com/your-username/flowchem.git

    • Change the directory: cd flowchem

    • Add the upstream repository: git remote add upstream https://github.com/cambiegroup/flowchem.git

    • Now, git remote -v will show two remote repositories named:

      • upstream which refers to the flowchem repository

      • origin which refers to your personal fork

  2. Develop your contribution:

    • Pull the latest changes from upstream:

      • git checkout main

      • git pull upstream main

    • Create a branch for the feature you want to work on. Since the branch name will appear in the merge message, use a sensible name. For example, if you intend to add support for a new device type, called ExtendableEar a good candidate could be ‘add-extendable-ear-support’: git checkout -b add-extendible-ear-support

    • Commit locally as you progress (git add and git commit). Use a properly formatted commit message, and ideally write tests that fail before your change and pass afterward. If possible, include docstrings following Google docstring standard.

  3. To submit your contribution:

    • Push your changes back to your fork on GitHub: git push origin add-extendible-ear-support.

    • Go to GitHub. The new branch will show up with a green Pull Request button. Make sure the title and message are clear, concise, and self-explanatory. Then click the button to submit it.

  4. Review process:

    • Reviewers (the other developers and interested community members) will write inline and/or general comments on your Pull Request (PR) to help you improve its implementation, documentation and style. The review is meant as friendly conversation from which we all learn and the overall code quality benefits. Please do not let the review discourage you from contributing: its only aim is to improve the quality of project, not to criticize: we are very grateful for your contribution!

    • To update your PR, make your changes on your local repository, commit, run tests, and only if they succeed push to your fork. As soon as those changes are pushed up (to the same branch as before) the PR will update automatically. If you have no idea how to fix the test failures, you may push your changes anyway and ask for help in a PR comment.

    • A Github-action is triggered after each PR update to build the code, run unit tests, measure code coverage and check coding style of your branch. The CI tests must pass before your PR can be merged. If CI fails, you can find out why by clicking on the red cross icon and inspecting the test log. (To speed up this cycle you can also test your work locally before committing.)

    • After review, a PR will be merged in the main branch and will be part of the next release.

  5. Document changes

    • If your change introduces support for a new device make sure to add the relevant documentation for it. As conceptual framework for our documentation we are inspired by Diátaxis.

Guidelines

  • All code should be documented with docstrings (in Google format) and comments where appropriate.

  • Possibly, all new code should have tests.

  • We use black as code formatter not to waste time discussing code style.

  • You can install pre-commit to run black and other linters as part of the pre-commit hooks. See our .pre-commit-config.yml for details.

Testing with pytest

To run the tests pytest and some pytest plugins are needed. To install them run:

pip install flowchem[test]

If possible, new code should be accompanied by relevant unit tests, see more details in testing.

Documentation

The documentation is written in Markdown and a new version of it is automatically build after each commit in the main and docs branches on readthedocs.com.

It is also possible to build the documentation locally. Install the packages required (sphynx, myst-parser and more) by running:

pip install flowchem[docs]

Then, from the ./docs folder:

make html

This will generate html files in the _build/html subdirectory.