Developer documentation

MAICoS is a community effort, driven mainly by scientists working on fluids at interfaces. It is developed in open collaboration with a number of contributors from across the world. As such, we welcome contributions from anyone who is interested in improving MAICoS, and we are committed to providing a welcoming and inclusive environment for all contributors.

To ensure a positive and productive experience for everyone involved in the project, we have established the following guidelines for contributing. Please read them carefully before submitting any contributions to MAICoS.

Code of Conduct

As contributors and maintainers of MAICoS, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting merge requests or patches, and other activities.

We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion.

Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.

Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.

This code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community.

Instances of abusive, harassing, or otherwise unacceptable behavior should be reported to the project maintainers.

This Code of Conduct is adapted from the Contributor Covenant, version 1.1.0, available at https://contributor-covenant.org/version/1/1/0/

Getting involved

Contribution via pull requests are always welcome. Source code is available from GitHub. Before submitting a pull request, please read the developer documentation and open an issue to discuss your changes. Use only the main branch for submitting your requests.

By contributing to MAICoS, you accept and agree to the following terms and conditions for your present and future contributions submitted to MAICoS. Except for the license granted herein to MAICoS and recipients of software distributed by MAICoS, you reserve all right, title, and interest in and to your contributions.

Getting started

To help with developing start by installing the development dependencies. Our continuous integration pipeline is based on Tox. So you need to install tox first

pip install tox
# or
conda install -c conda-forge tox

Then go to the MAICoS develop project page, hit the Fork button and clone your forked branch to your machine.

git clone git@github.com:your-user-name/maicos.git

Now you have a local version on your machine which you can install by

cd maicos
pip install -e .

This install the package in development mode, making it importable globally and allowing you to edit the code and directly use the updated version.

Useful developer scripts

The following scripts can be useful to developers:

  • ./developer/clean_dist_check.sh: Clean dist files. Useful before/after tox -e build

  • ./developer/clean_tempfiles.sh: Remove all generated files related to Python, including all build caches.

Automated Contributions Policy

Contributing to MAICoS requires human judgment, contextual understanding, and familiarity with concepts related to fluids at interfaces. It is not suitable for automatic processing by AI tools.

Please refrain from submitting issues or pull requests generated by fully-automated tools. Maintainers reserve the right, at their sole discretion, to close such submissions and to block any account responsible for them.

Review all code or documentation changes made by AI tools and make sure you understand all changes and can explain them on request, before submitting them under your name. Do not submit any AI-generated code that you haven’t personally reviewed, understood and tested, as this wastes maintainers’ time. To enhance the review process, please indicate if significant parts of your contribution were generated or modified by AI tools (typicically this is the case beyond simple code suggestions e.g. inside IDEs).

Please do not paste AI generated text in the description of issues, PRs or in comments as this makes it harder for reviewers to assess your contribution. We are happy for it to be used to improve grammar or if you are not a native English speaker.

PRs that appear to violate this policy will be closed without review.