Contributor guidelines

Owned by Arne Vandamme
Last updated: Nov 12, 2015
5 min read

First of all we think it's great you want to help improve Across.  You are welcome to fork any of the repositories and launch a pull request.  The following is a list of guidelines that you probably should follow if you want to get your PRs accepted in the speediest fashion.

Applicability

These guidelines are the standard for all Across related repositories maintained by the core team.  These include Across itself as well as all standard modules.

Use the right branch

In most repositories - unless you are fixing an emergency bug - you should branch of develop and merge back to develop in your pull request.  Any repository that uses a different flow should detail so in the README.md at the root of the repository.  If multiple develop branches exist and you are unsure which one to use, ask the maintainers.

Talk English

Please remember to use English everywhere:

  • on this wiki (Confluence)
  • in JIRA
  • commit messages
  • in code (class names, properties, inline comments)
  • javadoc
  • reference documentation
  • user interface
  • resource files

Though we understand it's sometimes not easy, we do appreciate it if you pay some attention to correct spelling.  Especially when it comes to the code where correcting spelling errors post factum can introduce breaking changes.  A resource like Dictionary.com can be helpful.

Resource files for other languages are welcomed, but please ensure they are correct and complete if you include them.

Link to a JIRA issue

All repositories (should) have their equivalent JIRA project.  See if there's no JIRA issue yet matching with your intentions and If necessary create your own.  This allows other developers to get involved more easily and also serves as a great help for generating the release notes.

If you launch a PR without a JIRA issue, you will most likely be declined with the question to create one first.

As a good practice: whenever possible name your branch and start your commit messages with the JIRA issue id.

Only include issue ids to the Across JIRA projects in your commits.  External issue ids (eg MYPROJ-1235) are meaningless for the Across community and clutter the commit history.

Code style & copyright

Most contributors use IntelliJ IDEA as their favourite IDE and most repositories include the .idea project directory.  Code style settings and copyright should be attached to the project so it should be really easy to apply them.

A good practice is to reformat the code, optimize imports and update the copyright on every commit.

Testing

As much as possible, help us keep a good codebase and write tests!

Because we like software craftsmanship: without tests small changes might be, but large additions to the code (eg new features) will definitely be refused.

Unit tests

This should go without saying: unit tests are expected wherever useful (hint: they most often are).  Our conventions are unit test classes start with Test*.

Integration tests

If you code depends on different module configurations, you should test different configurations in separate integration tests.  As a general rule, modules should have some integration tests that bootstrap Across context configurations and verify the exposed services.  Testing correct bootstrapping of a module is an absolute minimum.

Additional integration tests, for example using mock mvc, are very welcome as well.

Cross-database testing

As a general rule, standard modules performing schema changes are developed and tested against HSQLDB, Oracle, MySQL and SQL Server.  Any schema changes are required to work on all these DBMS systems.

Test classes that should be run against external resources (databases) should start with IT*.  This ensures they will execute in the Maven verify phase, after the other unit tests.  This will also ensure that our build agents run the tests against the different DBMS implementations.  You can find more information on this in the old documentation about integration testing.

Acceptance tests

Some modules include one or more test projects that start a website and run automated acceptance tests against it.  This is advised and we might insist on it for functionality that is very UI driven.  Though not an absolute restriction, these acceptance tests are usually executed using Cucumber Web Bridge.

Documentation

We consider solid documentation absolutely vital.  It cannot be expected that all developers know the ins and outs of every module, and in a fast evolving landscape reliable documentation should be a beacon of trust.  

As with tests, anything but trivial pull requests without any form of documentation are almost certainly to be refused.

We consider 4 sources of documentation, of which Javadoc and Reference documentation are most important for contributors:

Javadoc

Geared towards all contributors and source-code reading developers.  All public methods and classes should include decent Javadoc.  Whenever you modify a class and do more than cosmetic changes, add yourself as an author with your full name.

Additional inline comments are optional but very welcome.  Just remember to write it in English as well.

Reference documentation

The reference documentation is usually generated from AsciiDoc in the project source folder (search for index.adoc).  It should contain the explanation of all features that a module provides as well as the configuration options and inter-module dependencies involved.  Whenever you add a new feature or configuration option, you should update the reference documentation as well.  Reference documentation should really be as complete as possible, without delving in to too many implementation details.

Reference documentation is not the same as tutorials.  The reference documentation should give as good as possible a view of the functionality, without necessarily going into a structured explanation of how to achieve something.  If you want to write a tutorial we will gladly publish or link it on the Confluence site.

You can find an overview of all reference and javadoc documentation on: http://across.foreach.be/docs.

When writing AsciiDoc, try to use the sentence-per-line technique. A good presentation with tips for writing documentation can be found here.

Confluence (this wiki)

This is the central hub that connects all other documentation.  The Confluence pages are usually managed by the module maintainers but any registered user can comment.

README.md

Geared towards contributors that use the Bitbucket repositories as entry point.  Apart from specific build instructions and base copyright rules, the readme should mostly refer back to the Confluence site.

Unless you change the build instructions, you will rarely need to make changes to this file.

Contributing in the wild

Have some time to spare and want to help improve Across?  The JIRA projects for both core and the standard modules have lots of issues in the backlog you can get started on.  We'd advise you to start with something small however (eg a simple bugfix).  Contact the issue reporter directly or through issue comments if you need more information.

 

Following the guidelines requires a bit more effort, but it will make it more likely your pull request will be accepted and will greatly help in maintaining a high standard for our projects.

Happy coding!