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.
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
If you followed the steps for the initial development setup you have everything at your hands:
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.
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
- refactor: 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.
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.
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
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
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.
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
the right versions from the dependencies listed in setup.py and the
dev-requirements.in and is manually run by the maintainers regularly.