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!

Community

We aim at creating a community around flowchem, by incentive the participation from a diverse group of contributors. Please read the Contributor Covenant we adopted as Code of Conduct for guidance on how to interact with others in a way that makes the community thrive.

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 ExtendibleEar a good candidate could be ‘add-extendible-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.

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.

Tests

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

pip install flowchem[test]

Building docs

The documentation is automatically build for each commit at readthedocs.com. To build it locally, sphynx, myst-parser and other packages are needed. To install them run:

pip install flowchem[docs]

Then from the docs folder run make html to generate html files in the _build subdirectory.