Updating CONTRIBUTING.md with more developer guidelines

Background

The current CONTRIBUTING document is in draft state and needs to be updated.

Also I’ve noticed a discrepancy in code-style across all the modules. There is a wide mix of tabs and space. The import order varies wildly. There are some other few discrepancies as well.

These discrepancies will only continue to grow the more developers we add to the project. The primary reason to use a single code style is to reduce change noise.

Without a single codestyle pull requests by default will have lots of noise in the form of import order changes, whitespace changes, etc. Fixing this noise is difficult as it involves fighting your IDE’s settings.

Proposal

This can all be nipped in the bud by specifying an official Katharsis project formatter for Eclipse and IntelliJ.

Most of the developers are already using the same style, in theory, so there is no reason to change. The only settings that need tweaking or whitespace and import order.

While at it we can spruce of the Contribution guidelines and specify default ISSUE and PR templates to encourage correct and useful contributes from the community.

Tabs or Spaces

According to the Intellij “Problematic whitespace” checker, there are:

If we use tabs: 628 files that must be changed. If we use spaces: 506 files that must be changed.

I hope we can make a decision here that is fast and friendly.

Import order

I propose the following import order:

This will keep the imports organized and clean.

Hosting the formatters

• Do we put the formatters in the katharsis-framework/katharsis-framework repo or in a separate repo such as katharsis-framework/katharsis-etc?

TODO

If everyon is in agreement then we can:

• Update Contribution guidelines and add project issue and PR templates (see PR #244 )
• Decide on tabs vs spaces.
• Provide importable formatter settings for Eclipse and Intellij, and where to put them for download
• Apply the new formatter across the entire project to normalize our still from here on out

[remmeier]

I prefer tabs. But I’m also able to sleep at nights if spaces are used.

[Ramblurr]

Yes, like @masterspambot said the main problem with not having a project standard is that the PRs and commits are very very noisy as the different IDEs apply formatting to a file when changing only a few lines.

In the slightly worse case the dev might have the IDE to only apply formatting rules to lines they actually change, but this ends up with inconsistent styles as some lines are 80 chars with spaces and others are 100 with tabs and all { on new lines.

I’ll setup that maven plugin and see if it behaves sanely.

(also, I’m for longer lines too.)