contributing.md

Contributing guidelines

commits and commit message

Commit messages are for traceability. Any dev should understand the whys of a given implementation by looking at commits. This means:

• Write useful commit messages
• Avoid modyfing code when not directly needed

The general rule is: Use common sense, ask yourself what a dev, in 18 months, should read when he inspects a line you wrote because he needs to know why things are coded like this.

Commit message

The general format is:

TICKET_REF: ACTION SUBJECT

MULTILINE_BODY

where

• TICKET_REF references a bug tracker, such as ATCR-819
• ACTION is a verb such as "fix" or "implement"
• MULTILINE_BODY details your changes if necessary. You can use bullet points and paragraphs

Please follow these rules:

• use imperative tense
  • GOOD: implement user login
  • BAD: implemented user login
  • BAD: user login
• use a proper verb
  • example: fix, implement, change, refactor
  • BAD: refacto xxx, do xxx
• write them in english
• do not document your struggle with code review or code iterations
  • BAD: try to work aroung flyway not working properly. Again
  • BAD: changes a few things after review
  • Why: it is useless information, it doesn't contribute to help understand the behaviour and changes on the code
• Add ticket reference
  • example: ATCR-225: fix ...
  • There should be a ticket requiring your change.
• Add details when commiting big changes
  • insufficient: refactor PrediagController
  • use commit body to add details, what have change and why
• A commit is a whole and single unit of change.
  • If a commit changes several unrelated matters, split em (ex: Changing a build pipeline and fixing a typo in an HTML templates)
  • If you have several commits that should be combined in one, squash em
    • ex: when you push 10 or more commit because you iterate and need to commit to test the build, but most of your commits are trial and error and irrelevant to future inspection
  • Ideally, any commit should build, a commit which doesn't build, for which tests doesn't pass shouldn't exist.
• Break these rules if they'd lead to a stupid situation.

Avoid commits that erase precious history

When you git blame, you can inspects all lines of code and why they were changed to be the way the are. It is especially annoying when you dig for searching motives behind changes to see commits like "refactor xxxx, reindent xxx" Avoid modifications that make git blames hard to read:

• reindentation
  • indent properly the first time
• code moving
  • unless strictly necessary, avoid it
  • be proactive and organize your code the best way the first time it's written
• Lists upgrading, such as constructor arguments (often dependencies)
  • Some language syntax and some code formatting rules mess the git history a lot:
    • When identation depends on identifier size, it sucks, because if you change the name, it messes the indentation above
    • When you add an argument last, it breaks two lines because the last element isn't followed by a comma
• identifier renaming, especially public members renaming