Analytics/Wikimetrics/CommitGuidelines

= Goal = The goal of this document is to define a criteria to evaluate commit "goodness".

Feature versus Atomic
We prefer atomic commits and we are trying to get towards more atomic, more logic commits iteratively. We shouldn't block things that are not atomic but it is to be understood that when possible commits should be very focus.

What does Atomic mean?
It means that commits should not contain multiple unrelated changes; try and make piecemeal changes if you can. It is worth to have in mind that, in most cases, atomic commits will be small in size but this is not always the case. We could have, for example, a commit that changes the format of every line we are logging to the logs. It will be a large commit but focused on one aspect.

Value Proposition
Atomic commits easier to CR, easier to spot failure and easier to rollback but their advantages do not come without cost, in a large stream of commits it might be hard to see what is the overall goal. We will try to keep track of changes that belong together using "topics" in Gerrit.

Testability
We feel we are doing pretty good when it comes to testability. We should emphasize more unit testing versus integration testing unit testability: Strive for unit-testing coverage as much as possible, using mocking, etc. We are doing good here. overall testability -> see Deployability

Deployability
We should strive to do consistent, complete, environment-aware commits Environment-aware means that all required repos should have a patch prepared (need not yet be merged). Example: your change adds a new piece of infrastructure that needs to be started by puppet. You should submit two patches (or maybe three) for CR. The changes to wikimetrics codebase and teh chnages to puppet modules. Please make sure that ops CR puppet changes. Depending on the change puppet code might need to be deployed before or after (likely after) but regardless of deployment schedule the puppet code should be reviewed about the same time the wikimetrics code is reviewed. Changes on wikimetrics code can link to puppet changes.

Commits should not require to be deployed in groups

Continuous Integration
We should set up Continuous Integration to development and move stable to staging once ready. If needed we should be able to take over staging environment and test there.

Gerrit: Tool limitations
We are using Gerrit as our code review tool, it works reasonably well but we see two main limitations: merge commits and usability.

Merge Commits
Merge commits are annoying in Gerrit cause you just ...cannot do them, Gerrit is opinionated as to how commit history should look like and the tool is geared towards "rebases".

Usability
Gerrit is definitely not intuitive, specially if you have used other CR tools. Developers that might have used source control for years have a hard time wrapping their minds around the fact that there are no branches nor merges. It definitely has a learning curve for people that are coming from outside. Now, that being said, once learned it behaves very consistently.

Documentation
Not updating READMEs, diagrams and inline documentation all that stuff is should be blocker during CR. Updating Wikipages is optional, but should be done. Shared responsibility with the Product Owner. Diagrams will be updated using yED.