Contributing¶
Documentation¶
If you like to contribute to this project, please try to follow the contribution specifications!
The Documentation is in reStructuredText.
All Files are in the masymos-core
project in Folder /dev/doc
.
Consistency¶
To try keep the code and the documentation consistent, please stay with the following conventions.
General¶
- please use exactly 4 spaces to indent anything
- don't use TABs (
\t
) - referencing headings in the same document
- create ref-links
.. _my_ref_link:
- reference by
:ref:`my_ref_link`
- example-link to Consistency
- create ref-links
- check the Output after you call
make html
- are there any warnings, errors,…?
Titles and Headers¶
- each page has a title describing the topic
- this title is over- and underlines with
*
- this title is over- and underlines with
- Header 1 is underlined with
#
- Header 2 is underlined with
=
- Header 3 is underlined with
-
- Header 4 is underlined with
~
- Header 5 is underlined with
^
-Special Structures¶
rst_directives.rst
defines global directives, include it with.. include:: rst_directives.rst
, i.e. inline code highlighting
Contribution to MaSyMoS¶
General guidelines¶
Project Version numbering¶
- the projects version is stored inside the
pom.xml
in project.version - version schema:
major.minor.bugfix[-STAGE]
- usually functional changes are minor, except, the project owner decides, that there is a major release
- the version will ONLY be edited, if the test or master branch releases the new change (there is no need to edit the version in your development environment)
- when increasing the minor, set bugfix to zero
- when increasing the major, set minor and bugfix to zero
- for the
-STAGE
you usually use-TEST
for all test versions - for the productive version, the stage is omitted
- version schema:
Using the CHANGELOG.md¶
- every project has it's own
CHANGELOG.md
-file - everyone can see every change between version X and Y
- see an example changelog for GitLab here
- every project has it's own
- for general information about Changelogs, please read this
- How to use the Changelog?
- when you added/changed/removed something (in your fork or branch) add that information to the
CHANGELOG.md
under the heading## [Unreleased]
- please always add the link to your issue for anything you add there
- i.e. add
MaSyMoS/masymos-core#42
- i.e. add
- when your fork/branch is then merged into the master, your changes will then get the right heading with the pom-version-number and the date
- when you added/changed/removed something (in your fork or branch) add that information to the
Working with the projects¶
- the projects in https://github.com/MaSyMoS are our master; don't push your changes there
- instead Fork the repository an work on your copy
- the master branch is the productive release branch
- there are maybe other important branches like test
- changes are includes via pull-requests
Working with git¶
- all release versions get a tag containing the version
- for a clean history we can make use of the git-feature
rebase
Commit and Push¶
- comment your commits!
- do not use prefixes like
dev:
,fix:
; better use verbs likeadded
,changed
,fixes
,… - link your commits to the related issues, i.e. if you worked on Issue Nr. 23 your comment could be something like
- MaSyMoS/masymos-core#42 removed bug in Auth.java
Content of your Commit¶
- never push functional commits to the master branch! (i.e. Bugfix, Features, internal changes) → use branches or forks!
- never combine functional and non-functional changes in one commit
- example: changing the formatting of all files AND a bugfix → nobody will ever find your changes for that bugfix
- usually it's good to have exactly one commit per specific change
Working with GitHub¶
Working with Issues, Labels, Milestones¶
- for every task create an Issue in the project you're working
- if your task affects MaSyMoS on a Meta-Level or more the one part, use the
masymos-core
project
- if your task affects MaSyMoS on a Meta-Level or more the one part, use the
- the first comment in an issue contains a current overview about the status of this issue
- use markdown and checkboxes inside this comment to mark important things and todos
- as headlines you can use
- Overview - general description
- ToDo - all single steps to take to resolve this issue → use checkboxes here!
- History - this can be important on bigger issues that will stay open for a longer period of time
- Questions - write down all questions and answers for this issue here
- Issues are not Documentation
- the questions, answers and decisions must be transferred to the documentation before closing the related issue
- issues can be grouped by Labels
- i.e. prio_high, type_bugfix, cat_quality,…
- Milestones can be used to create time lockable packages of issues
General Flow for code changes¶
1. Create Issue. 1. Generate Branch from Issue. 1. Stay in that branch for your changes. 1. Create Pull-Request for your branch. 1. Review of the Pull-Request by another Developer. 1. Merge of the Pull-Request into the test branch. 1. After running all tests, the changes can be merged into the master branch.
Working with your IDE¶
- feel free to use eclipse
Important
check your IDE!
- set default Encoding and line delimiter (most important on Windows!)
- Window → Preferences → General → Workspace
- Text file encoding:
UTF-8
- New text file line delimiter:
UNIX
(\n
)
- Text file encoding:
- use spaces for tabs, tab-width: 4 spaces
- Window → Preferences → General → Text Editors
- Display tab width:
4
- [x] Insert spaces for tabs
- Display tab width:
Working with Java¶
- new code should also bring the needed JUnit-Tests
- got for a test coverage of 60% or more
- do not build cycles, never! (A uses B uses C uses A)
- pay attention to the metrics, check with…
Java programming¶
- in log4j2 use placeholders, i.e.
LOGGER.debug("this is my error with param {}", param, e)
- use
TODO
andFIXME
in comments describing Todos and Fixmes o.O - i.e.
//TODO exception XYZ thrown, needs to be catched
- i.e.
- use