Skip to content

Contribution Workflow

Jump to bottom
jcomedouteau edited this page Mar 26, 2021 · 8 revisions

This documents aims to describe the contribution workflow the shanoir-ng code repository.

Pull requests

A contributor may submit a pull request, based on the branch [develop]. This pull request may be accepted if the following requirements are met :

  1. The code quality meets up our requirement.
  2. When applicable, the code should provides it’s own integration/system/unit tests.
  3. In addition to that, the pull request must be accompanied with a clear description of how to test it manually.
  4. The pull request is properly tagged with the copyright regime you intend the code to be integrated with. We are susceptible to accept the following :
    1. The contribution is minor, I certify I have developed it or have the right to contribute the code, and all associated rights are assigned to Inria.
    2. The contribution is significant and I will send the proper paperwork to assign copyright to Inria.
    3. You are asking that this code be integrated even if you or your employer is keeping all the rights to the contribution and is licensing it under the GPL license. If you intend to work on the code base and request integration of your work under this regime, please ask before working so that we can agree that this is acceptable for the foreseen contribution.

Commiters

When accepted, the submitted code becomes part of the "develop" branch, meaning it will included in the next release.

Acceptation is performed by one of the project’s committers. The current commiters are :

Regular contributors are invited to ask to become committers if they wish. Any request is approved by the Shanoir Consortium’s Executive Committee.

Rules beetween the commiters

1 - Code quality requirements

Java

Code quality requirement is based on google's coding rules for java: https://google.github.io/styleguide/javaguide.html

Specific for Shanoir:

  • Javadoc is not mandatory everywhere, it has to be done on complex methods/class to specify the comportement of the method and the value expected for the arguments.

To help you realize this you can:

  • Install and use SonarLint with default configuration
  • Use save actions if using eclipse (additional action):
    • Convert control statement bodies to block
    • Remove unnecessary parentheses
    • Remove unused import
    • Add missing @override/Deprected annotations
    • Remove unnecessary casts
    • Remove redundant semicolons
    • Remove trailing spaces on non empty lines

For continuous integration, sonar will check your code and verify that you don't add new warnings.

Dockerfiles

The reference documentation is here: https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/

Angular

This section is under construction.

SQL scripts

SQL scripts have to be created in shanoir-ng/db_changes/[datasets/studies/import/users]/[XXXX]_[description].sql

  • [XXXX] a number incremented from the last SQL script written in this folder.
  • [description] a description of the pull request, and if possible the issue number #XXX

2 - Unit tests

Unit tests in Shanoir are strongly recommended, at least for methods containing important logical/functional parts.

However beans and "easy methods" and accessors may not be tested.

3 - Integration tests

Integration tests are currently managed by selenium in shanoir-test folder. If you have the time, such a test would be welcome.

More will come for the testing of APIs.

4 - GIT flow

We use a classic git flow.

  • master=> This branch is never unstable, it is merged from develop every week before the release.
  • develop => This is the branch on which every new branch should start and where every pull requests should end.
  • shanoir-issue#XXX => Feature of bugfix branch forked from develop and merged in develop at the end of its life.
  • shanoir-hotfix#XXX => Feature of bugfix on production. Forked from master then remerged in master AND develop.

XXX = github issue.

/!\ when creating a pull request, ALWAYS link it to its issue.

5 - Pull requests

  1. Pull requests should be as small as possible, in case of an important feature, plus split it in logical blocks.
  2. Pull requests should be documented, in the description and in the commits.
  3. A pull request can be created only if all these upper rules are respected.
  4. If a block of a feature is merged before being 'usable', it is possible to use feature flags to 'hide' it to non-developpers.
  5. After a comment on the pull request, the resolution should be fast so that it is as short as possible

6 - Code review

  1. Code review should be done soon (but not fast) after the pull request opening. It should no stay open more than 1 week.
  2. The reviewer has to check that every upper point is respected.
  3. Positive oriented language is generally a better option to pinpoint a mistake / a different point of view on the development.
Clone this wiki locally