How to contribute to agentMET4FOF

If you want to contribute back to the project, we provide a guide to get the desired system configuration aligned with our development environments. The code you produce should be seamlessly integrable into agentMET4FOF by aligning your work with the established workflows. This guide should work on all platforms and provide everything needed to start developing for agentMET4FOF. Please open an issue or ideally contribute to this guide as a start, if problems or questions arise.

Guiding principles

The agentMET4FOF development process is based on the following guiding principles:

  • actively maintain, ensuring security vulnerabilities or other issues are resolved in a timely manner
  • employ state-of-the-art development practices and tools, specifically

Get the code on GitHub and locally

For collaboration, we recommend forking the repository as described here. Simply apply the changes to your fork and open a Pull Request on GitHub as described here. For small changes it will be sufficient to just apply your changes on GitHub and send the PR right away. For more comprehensive work, you should clone your fork and read on carefully.

Initial development setup

This guide assumes you already have a valid runtime environment for agentMET4FOF as described in the Installation guide.

First install the known to work configuration of our dependencies into you virtual environment:

(agentMET4FOF_venv) $ pip install -r requirements.txt -r dev-requirements.txt

Advised toolset

If you followed the steps for the initial development setup you have everything at your hands:

Coding style

As long as the readability of mathematical formulations is not impaired, our code shoulds follow PEP8. We know we can improve on this requirement for the existing code base as well, but all code added should already conform to PEP8. For automating this uniform formatting task we use the Python package black. It is easy to handle and integrable into most common IDEs, such that it is automatically applied.

Commit messages

agentMET4FOF commit messages follow some conventions to be easily human and machine-readable.

Commit message structure

Conventional commit messages are required for the following:

Parts of the commit messages and links appear in the changelogs of subsequent releases as a result. We use the following types:

  • feat: for commits that introduce new features (this correlates with MINOR in semantic versioning)
  • docs: for commits that contribute significantly to documentation
  • fix: commits in which bugs are fixed (this correlates with PATCH in semantic versioning)
  • test: Commits that apply significant changes to tests
  • chore: Commits that affect other non-PyDynamic components (e.g. ReadTheDocs, Git , … )
  • revert: commits, which undo previous commits using git revert
  • wip: Commits which are not recognizable as one of the above-mentioned types until later, usually during a PR merge. The merge commit is then marked as the corresponding type.

Of the types mentioned above, the following appear in separate sections of the changelog:

  • Feature: feat
  • Documentation: docs
  • Fix: fix
  • Test: test

Commit message styling

Based on established community standards, the first line of a commit message should complete the following sentence:

If this commit is applied, it will…

More comprehensive messages should contain an empty line after that and everything else needed starting from the third line. Each line should not exceed 100 characters.

BREAKING CHANGEs

Since agentMET4FOF is not yet considered stable, we do not mark BREAKING CHANGES. As a consequence, at any time commits may changes parts of agentMET4FOF’s public interface so that previously written code may no longer be executable. If this occurs we try though, to mention migration strategies in the corresponding release descriptions.

Commit message examples

For examples please checkout the Git Log.

Testing

We strive to increase our code coverage with every change introduced. This requires that every new feature and every change to existing features is accompanied by appropriate pytest testing. We test the basic components for correctness and, if necessary, the integration into the big picture. It is usually sufficient to create appropriately named methods in one of the existing modules in the subfolder test. If necessary add a new module that is appropriately named.

Workflow for adding completely new functionality

In case you add a new feature you generally follow the pattern:

  • read through and follow this contribution advices and tips, especially regarding the advised tool set and coding style
  • open an according issue to submit a feature request and get in touch with other agentMET4FOF developers and users
  • fork the repository or update the develop branch of your fork and create an arbitrary named feature branch from develop
  • decide which package and module your feature should be integrated into
  • if there is no suitable package or module, create a new one and a corresponding module in the tests subdirectory with the same name prefixed by test_
  • if new dependencies are introduced, add them to setup.py or dev-requirements.in
  • during development write tests in alignment with existing test modules, for example test_addremove_metrological_agents
  • write docstrings in the NumPy docstring format
  • as early as possible create a draft pull request onto the upstream’s develop branch
  • once you think your changes are ready to merge, request a review from the agentMET4FOF collaborators (you will find them in the according drop-down) and mark your PR as ready for review
  • at the latest now you will have the opportunity to review the documentation automatically generated from the docstrings on ReadTheDocs after your reviewers will set up everything
  • resolve the conversations and have your pull request merged

Documentation

The documentation of agentMET4FOF consists of three parts. Every adaptation of an existing feature and every new feature requires adjustments on all three levels:

  • user documentation on ReadTheDocs
  • examples in the form of Jupyter notebooks for extensive features and Python scripts for features which can be comprehensively described with few lines of commented code
  • developer documentation in the form of comments in the code

User documentation

To locally generate a preview of what ReadTheDocs will generate from your docstrings, you can simply execute after activating your virtual environment:

(agentMET4FOF_venv) $ sphinx-build docs/ docs/_build
Sphinx v3.1.1 in Verwendung
making output directory...
[...]
build abgeschlossen.

The HTML pages are in docs/_build.

After that you can open the file _./docs/build/index.html relative to the project’s root with your favourite browser. Simply re-execute the above command after each change to the docstrings to update your local version of the documentation.

Examples

We want to provide extensive sample material for all agentMET4FOF features in order to simplify the use or even make it possible in the first place. We collect the examples in the subfolder agentMET4FOF_tutorials.

Comments in the code

Regarding comments in the code we recommend to invest 45 minutes for the PyCon DE 2019 Talk of Stefan Schwarzer, a 20+-years Python developer: Commenting code - beyond common wisdom.

Manage dependencies

We use pip-tools for dependency management. The root folder contains a requirements.txt and a dev-requirements.txt for the supported Python version. pip-tools’ command pip-compile finds the right versions from the dependencies listed in setup.py and the dev-requirements.in and is manually run by the maintainers regularly.

Licensing

All contributions are released under agentMET4FOF’s GNU Lesser General Public License v3.0.