Contribution Guidelines¶
Contributions to AMNES are always welcomed and appreciated. Nevertheless there are a few guidelines which must be followed.
Contributor License Agreement¶
By contributing to this project, You accept and agree to the following terms and conditions for Your present and future Contributions submitted to this project. Except for the license granted herein to this project and recipients of software distributed by this project, You reserve all right, title, and interest in and to Your Contributions. All Contributions are subject to the following Developer Certificate of Origin and License terms.
Project Guidelines¶
Labels¶
We use different labels for Issues and Merge Requests to organize our workflow and optimize development progress. In the following paragraphs you will find all currently used labels and guidelines, which label types have to be set and where which label can be used.
Type Labels¶
These labels are used to determine the type of the Issue or Merge Requests. Every Issue and Merge Request must have exactly one type label set.
Type Labels for Issues and Merge Requests¶
| Label | Purpose |
|---|---|
type::feature |
Changes or discussions about new features (no requests). |
type::improvement |
Changes or discussions about improvements. |
type::devops |
Issues and Merge Requests for DevOps. (CI, CD, Workflow) |
type::test |
Used for flagging changes of and operations on tests. |
type::bot |
Used for Issues and Merge Requests created by bots. |
type::project |
Issues and Merge Requests targeting Project Management. |
Type Labels only for Issues¶
| Label | Purpose |
|---|---|
type::bug |
Used for Issues which report or describe one or more bugs. |
type::feature-request |
Indicates a feature request which must be discussed. |
type::bundle |
Flags Issues which organize other Issues. (Grouping, Epics) |
Type Labels only for Merge Requests¶
| Label | Purpose |
|---|---|
type::fix |
Indicates a fix of a reported bug (used in conjunction with type::bug Issues). |
Priority Labels¶
These labels are used to order and prioritize Issues and Merge Requests which helps developers to decide which task should be done next. Every Issue and Merge Request should have a priority label assigned to it. More the one priority label is not allowed.
| Label | Purpose |
|---|---|
priority::high |
Urgent Issues and Merge Requests which must be solved ASAP. |
priority::medium |
Issues and Merge Requests which should be solved in the near future. |
| No Priority Label. | Default Priority. |
priority::low |
Issues and Merge Requests which should only be worked on if time is available. |
Workflow Labels¶
These labels indicate the current status of an Issue or Merge Request. Every Issue and Merge Request may have a workflow label assigned to it. More than one workflow label is not allowed.
Workflow Labels for Issues and Merge Requests¶
| Label | Purpose |
|---|---|
workflow::blocked |
Issues and Merge Request which are blocked by another Issue or Merge Request. |
Workflow Labels only for Issues¶
| Label | Purpose |
|---|---|
workflow::ready-for-develop |
Issues which can be picked up by a developer. |
workflow::in-develop |
Issues which are currently in development. |
Workflow Labels only for Merge Requests¶
| Label | Purpose |
|---|---|
workflow::ready-for-review |
Merge Requests which are ready for a review. |
workflow::in-review |
Merge Requests which are currently in review. |
workflow::ready-for-merge |
Merge Requests which can be merged. |
Area Labels¶
These labels are used to classify Issues and Merge Requests into specific topics and areas. Every Issue and Merge Request may have multiple area labels assigned to it.
| Label | Comment |
|---|---|
area:controller |
AMNES Controller Component |
area:worker |
AMNES Worker Component |
area:storage |
AMNES Storage Backend |
area:communication |
Communication between AMNES components |
area:core |
AMNES Core |
area:ctl |
AMNES CTL Command |
area:documentation |
AMNES Documentation |
area:nodemodules |
Built-In Node Modules for AMNES |
Branches¶
The main branch for AMNES is develop which is also the branch used to generate this documentation.
There are also contribution branches contribute/* which are used to accept public merge requests.
If you want to contribute to AMNES using a public platform as GitLab.com, you need to target the corresponding contribution branch (contribute/gitlab for GitLab.com) to get your merge request accepted and merged.
These contribution branches will be synced with develop by AMNES Project Group.
Release Tags are created from commits of release branches named as releases/*.
If you need to create a seperate branch for testing or your merge request, it is recommended to prefix it with a meaningful tag, e.g. task/fix-nuclear-bug or doc/update-installation-guide.
Code Guidelines¶
Code Style¶
To prevent unnecessary diffs and changes, AMNES uses the Black code formatter. In addition to this, pylint, flake8 and isort, are used as a basic linters and for static code analysis of python sources.
Important
AMNES uses type checking by mypy which must be used.
In addition to isort, you must follow these import rules:
-
Relative Imports like
from ..foo import barare used by AMNES modules to import other AMNES modules. -
Absolute Imports like
import amnes.foo.barare used by test sources and external modules.
Commit Messages¶
Writing clean commit messages is essential. There is very basic Blog Article by Tim Pope about how to write a good commit message. The most important rule to follow is the 50-75-Rule, because otherwise the commit messages are not correctly displayed in used GUIs.
Tests and Test Coverage¶
AMNES uses pytest for part of its code.
Everything located in amnes.core package or any of its subpackages must be completely covered by test code.
Node Modules or parts of them should be covered, if it is possible.
If you are not sure, if your contributed code needs tests, ask an AMNES Developer.