.. _contrib_main: ************ Contributing ************ .. contents:: :depth: 4 :local: 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``. .. _consist: 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 :ref:`consist` - 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 ``*`` - 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 Helpful Links: ============== - `An introduction to Sphinx and Read the Docs for Technical Writers `__ - `reStructuredText Primer Documentation `__ - `ReStructuredText-CheatSheet `__ 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 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 `__ - `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`` - 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 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! - to keep track of all changes → provide a small text for *each commit* - the length of the first line of your commit can be up to 72 Bytes long - if you need more comments separate them with two line breaks - see `here `__ and `here `__ - do not use prefixes like ``dev:``, ``fix:``; better use verbs like ``added``, ``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 Merge ~~~~~ - never mix a merge with any commit (functional or non-functional) - if you're merging two branches, the resulting commit has two parents → therefore a diff will be very difficult - so for a merge ONLY resolve conflicts, never add/edit/delete something 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 - 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``) - use spaces for tabs, tab-width: 4 spaces - *Window → Preferences → General → Text Editors* - Display tab width: ``4`` - [x] Insert spaces for tabs 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… - `SonarLint `__ - `FindBugs `__ or `SpotBugs `__ - `Project Usus `__ - … Java programming ---------------- - in log4j2 use placeholders, i.e. ``LOGGER.debug("this is my error with param {}", param, e)`` - use ``TODO`` and ``FIXME`` in comments describing Todos and Fixmes o.O - i.e. ``//TODO exception XYZ thrown, needs to be catched``