Code Keeper Guide

As the code keeper, you are not working as a developer on the project but your work is to make the developers life easy, and to keep the contributing process enjoyable.

As the code keeper, you are in charge of

• Make it easy for everyone to build and run Sigmah on its local development environment
• Making sure that official sigmah repository is sane
• Keep the source code clean
• Maintaining a release process which ensure delivered artifacts are high-quality
• Releasing

Your role is critical, especially since Sigmah is developed by multiple organisations and individuals. Your goal is to make everyone work together, easily, withtout friction and headaches.

This guide is here to help you achieving this and above goals are detailed below.

As the code keeper guide, you are not a developer on the project but you managing developers so you are expecting to be a developer or to have practiced development as a day-to-day activity. A past experience working on the Sigmah codebase would be a big plus. Also, knowledge of the technical stack (Java, GWT, Hibernate, etc.) is a must-have.

Since you will be working on the build, knowing Maven and its release process will help.

Collaboration on team is based on git SCM and github as a collaboration platform, so you should be at ease with those tools.

We want everyone to easily become a contributor so, as a code-keeper guide, you must care about that the very firsts steps of a wannabe contributor won't be discouraged by having to take 3 days to make something work.

The motto here is “anybody can get the sources and build successfully at anytime”.

You have to make sure the master branch of the official repo (this is the HEAD so, this is what anybody who is cloning the repo will get) is always ready to build effortlessly. People want to works on their issue, not going deep in a cluttered build process or a fighing for a dependency resolution.

There is a travis build that check that. The code keeper must maintain it. Be aware that the build is not stand-alone and rely on a postgresql instance with a proper, up-to-date schema is here: see `.travis.yml` file and travis postgresql database setup documentation for details.

If the build fail, find the culprit! Travis keep an history of all the builds and a build is made after each push so it would be easy to find which commit broke the build.

Run a build locally to make sure you have the same error as given be travis-ci. If not, it may be an environmental issue (your database is in a different state, Java versions differ, Maven versions differ… that sometimes hard to guess).

Running Sigmah require a database, we tried to ease that for developer by providing a one-line command way to create all the database schema. Check that it works, all the flyway migration files should be self-sufficient for Sigmah to work properly!

The source code repository is more than a way for the developers to synchronize. The repository gathers more precious information than only the last version of the code.

The git history provide many information about the way Sigmah have been gradually built. When the code is not self-explenatory, the history may reveal a lot about the intentions, the errors, the whys. The history of all the commits made on the project forms a huge base of information that may be of great help to find the source of bugs.

As the code keeper, your are also responsible for keeping the history clean and relevant to what really occured during the development process.

• check that every commit author is the actual author, so we can reach someone for help
• merge one thing at once, so that each possible state of the source-code has its own commit. If you want to fix something while merging, commit on the branch first. The merge commit should have no other modification than conflict-resolutions
• keep the graph linear as far as possible: merge branches in master, avoir creating branches bases and branches and merge everything into everything, keep the branches short-lived: a branch with no commit since days should be merged or deleted.

Well, this one is obvious. It's easier and funnier to work on a application well-designed, with a solid architecture and maintenable code. Noone enjoy creating something when everyline is puzzling.

As the code-keeper, you are not a developer, so can't control the quality of the code written but, at least, you can check it.

The github pull-requests mechanism is a great tool for that.

• you can comment every code contributed and ask for corrections, it's a way to ensure that all the developers share a common set of practices (which one doesn't matter, consistency over the code base matters)
• developers may have opinions, preferences, habits, it's understandable, but consistency matters. If something have been designed with immutability, statelessness, or with another concern, respect the choice. Noone can't rewrite everything.
• as explained above, we want to keep Sigmah easy to deploy so if a code change require a modification of the schema, a migration file is present and in a path making it suitable for flyway to detect and run it

Some common stuffs to review on the code:

• missing comments on complex code
• numerous conditional cases algorithm without future-proof catch-all (ie, switch whitout defaulting to something like throw new IllegalStateException()).
• cryptic variables/method name
• no respect for basic code conventions (like lowerCaseForVariableNames)
• smart usage of the JDK (use the suitable Collection implementation)
• immutability is prefererred over mutability (final everywhere, value objects without setters)
• does the application still work in deconnected mode?
• could unit test be added (with a reasonable cost/quality earned ratio)?
• could preconditions be added (should the application fail if this parameter is null)?
• are all the opened ressources lead to a Closeable#close() call in a finally statement?

This list could be infinitly extended, it's a life of development. You may complete this lists with the problem you found in the incoming PR.

Don't forget that talking about what is wrong with the developer, so he can't do better next time is a better attitude than let's fix this now without telling anyone and merge. The long term goal here is that developers should submit pull-requests with confidence and everything should be OK at the first try.

You may read ancient pull-requests to get examples of discussion. It's discussion so everyone can improve (you could lean new things!), it's not developer-shaming. Remembre that code is wrong, not coders.

The pom version should be set according to versions cycle.

Since the release process upload stuff to github, maven will need a token to authenticate on github.

Connect to github and in settings, choose “Personnal access token”. Create a new token and make sure the scope public_repo is checked.

Put the generated token in you maven settings.xml file, like so:

snippet.xml

<settings>
  <!-- ... -->
  <servers>
    <server>
      <id>github</id>
      <privateKey>1111111111111111111111111111111111111111</privateKey> <!-- replace this by your token -->
  </servers>
</settings>

Run a first build to make sure everything is OK.

Make sure no file miss its license header (if headers are added, commit those changes):

snippet.bash

mvn license:update-file-header

If it's not an RC release, enable the sigmah-check-bundles-integrity profile.

snippet.bash

mvn install -Psigmah-check-bundles-integrity

Automatic publication of basic version release

If the release is a basic version release (to be discussed with Sigmah product owner), you can proceed with following steps to automatically publish the release .war file on Github.

On branch master,

snippet.bash

mvn release:prepare
mvn release:perform

The .war file with be published to github releases page.