Contribute to agentMET4FOF
Whenever you are involved with agentMET4FOF, please respect our Code of Conduct . If you want to contribute back to the project, after reading our Code of Conduct, take a look at our open developments in the project board , pull requests and search the issues . If you find something similar to your ideas or troubles, let us know by leaving a comment or remark. If you have something new to tell us, feel free to open a feature request or bug report in the issues.
If you want to contribute code or improve our documentation, we provide this 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
follow semantic versioning
consider the PEP8 style guide, wherever feasible
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:
Sphinx for automated generation of our documentation on ReadTheDocs
pytest as testing framework backed by hypothesis and coverage.
our pipeline on CircleCI . All requirements for contributions are derived from this.
Coding style
As long as the readability of mathematical formulations is not impaired, our code should 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:
Releasing automatically according to semantic versioning
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 revertrefactor: commits, which contain to refactoring activities
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 change 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 check out 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
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.
Manage dependencies
We use pip-tools for dependency management.
The root folder contains a requirements.txt and a dev-requirements.txt
for Python 3.11. pip-tools’ command pip-compile finds the right versions from the
dependencies listed in setup.py and is manually run by the maintainers regularly.
Licensing
All contributions are released under agentMET4FOF’s GNU Lesser General Public License v3.0.
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.