Skip to content

Latest commit

 

History

History
255 lines (187 loc) · 12.4 KB

CONTRIBUTING.md

File metadata and controls

255 lines (187 loc) · 12.4 KB
Raw

Contributing to MontiThings

At the very heart of each software, there is always code. We do not write this code for the software to work, but to evolve! In other words, we write code for others (e.g., the future you) to read. As we believe in collaboration, we want to establish a workflow and principles that support that.

Care about the person that comes after you; it might be you! (Miško Hevery)

If you would like to contribute to this project, read and know all given information and sources provided by this file and the project owners!

Table of Contents

  1. Workflow
  2. Code Style

Workflow

In general:

  1. Fork the project.
  2. Create feature branch.
  3. Commit improvement.
  4. Integrate develop.
  5. Create pull request.

Git

This project's source code is managed with Git and is hosted on RWTH's GitLab.

Use merge instead of rebase!

Commit Messages

Consult this article on how to write good Git commit messages.

Use See #{issue-number} at the end of commit message to reference issue. Use Fixes #{issue-number}, Closes #{issue-number}, or Resolves #{issue-number} only in merge commits to develop.

GitFlow

Follow the GitFlow branching model with the following configuration:

[gitflow "branch"]
  develop = develop
  master = master
[gitflow "prefix"]
  feature = feature/
  release = release/
  hotfix = hotfix/
  support = support/
  versiontag =

We strongly recommend using SmartGit or at least git-flow.

Use the dash-notation with type-of-change first and all-lower-case letters for feature branches. For example:

feature/new-feature-plugin-x
feature/add-integration-test-for-x
feature/update-dependencies-version
feature/fix-bug-x
feature/amend-api-x
feature/refactor-delegate-x-responsibility

Useful type-of-change prefixes are (do not use abbreviations): new-feature, add, update, upgrade, fix, augment, amend, refactor, rename, remove.

Additional Note:

  • Never integrate two feature branches!
  • There must be no long-living feature branches!

Pre- and Post-Push

  • Pre-Push:
  • Post-Push:
    • Check that the build pipeline passes

Pull Request and Code Reviews

The master and develop branches are read-only! So the only option is to create a pull request for your feature branch. Name your pull request with your branch name.

Review code with all design, test, and code style principles of this readme in mind. Further, make use of all the information you can get; e.g., investigate the CI pipeline, run checks with coverage, perform code analysis, calculate metrics, etc.

For code reviews, a good starting point is the check list for pre- and post-push.

Read these recommendations.

Tools We Use

Check Conventions

Back to TOC

Code Style

Most importantly, write for readability. Consider Clean Code and Effective Java.

Clean code is simple and direct. Clean code reads like well-written prose. Clean code never obscures the designer’s intent but rather is full of crisp abstractions and straightforward lines of control. (Grady Booch)

Follow the SE Style Guide. We recommend using IntelliJ or eclipse for this project; therefore, we provide the code style configuration. Most importantly, indent with 2 spaces! (to tabs allowed).

The Intent Has to be Graspable in 5 Seconds

Good code reveals intent. (Kostadin Golev)

The reader of your method should grasp the WHAT? in 5 seconds! In other words, make methods small and use meaningful, intention-revealing naming. Separate intention from implementation!

Comments Do Not Make Up for Bad Code (Robert C. Martin)

For a class the 5 seconds deadline still holds!

Javadoc Every public Interface

There is nothing quite so helpful and satisfying as a well-described public API. (Robert C. Martin)

Write informative Javadocs; explaining the intent, clarifying restrictions, and warning of consequences. Link other program elements. State preconditions for parameters. Explain return values.

Note: Do not add @author. The team is responsible for the code; not one person.

Make Values final

All method parameters and most local variables are values; i.e., use the final keyword.

Never Write equals() and hashCode() Yourself

Never write those methods yourself! All IDEs can generate those methods for you. In IntelliJ, use the Java7+ template.

There Must Be No Commented-out Code

Delete those leftovers!

Don't Use Private

private variables and methods make it harder to derive from a class because it forces you to copy/paste code related to the private attributes to the derived subclass - even if you don't want then overriden. Use protected instead to prevent unrelated classes from accessing the variable.

Use Logger only

Never use System.out.print. Make use of the logging framework.

Some remarks:

  • Use logging sparingly.
  • Do not log in utility classes.
  • Use levels:
    • ERROR: extra information (in addition to an Exception) about errors that will halt execution
    • WARN : potential usage errors that should not halt execution
    • INFO : stuff the users might want to know but not by default
    • DEBUG: stuff that might be helpful for the developer for debugging

Back to TOC

Remark: This guide is based on the guide to the READER project provided by @Andrej.Dyck from Software Construction Group, RWTH Aachen University