Skip to content

Latest commit

 

History

History
93 lines (66 loc) · 7.01 KB

CONTRIBUTING.md

File metadata and controls

93 lines (66 loc) · 7.01 KB
Raw

Welcome

Welcome to the medInria Community!

Getting started

We offer binary version of medInria on med.inria.fr if you want to use the application.

To contribute to medInria development, please read carefully the Contributing to projects Github tutorial.

How development is organized

  • There are several "main" branches, for different ungoing medInria versions.
  • Several ungoing development branches exists, such as the master branch or those named medInriaX.Y.x. The master branch hosts the code of the lastest version under development. The medInriaX.Y.x ones host the main previous versions of medInria still in development.
  • We aim to only merge stable contributions, but only minimal effort is put to check side effects of these contributions (ie. contributed fixes or features are tested before a merge, but we acknowledge they might break things).
  • If you build your application based on medInria, we recommend you base your code on medInria's release branches, named vX.Y.Z.
  • Renaming, reorganizing and similar janitoring on the code will only be accepted during short periods before a new stable branch is created. This helps the flow of code between the stable branch and the main branches when fixes are applied to one of them.
  • Sometimes cherry-picking between branches fails. In that case, the port of a Pull Request (one commit or more) from one branch to an other has to be done manually. You should add the original Pull Request link in the new Pull Request message.

Rules for medInria participants

  • To propose a bundle of code use the Pull Request (PR) system. Pull request target branch should be one of the main branches.
  • Identify the nature of the change of your PR with appropriate title, description, label and if possible milestone.
  • Never auto validate Pull-Requests.
  • To report a bug, to open a discussion or to request an enhancement use Github Issues. Many labels are available to do this:
    • Bugs, three labels possible:
      • Critical (blocked a release, for example a crashing bug)
      • Major
      • Minor
    • Discussion (to ask something, to propose new architecture, to propose big changes …)
    • Enhancement (to propose a new behavior or a new standalone features)

Here is a brief summary of how community is structured:

  • medInria Users: people using medInria.
  • medInria Developers: people programming into medInria, modifying the API, writing plugins.
  • medInria Contributors: medInria Developers which propose their changes in medInria code via PR.
  • medInria Reviewers: people reviewing and merging the PR. This group is validated by the STC.
  • medInria Consortium: research centers and companies willing to share the cost of medInria development.
  • medInria Consortium Staff: administrators of medInria. This group is directed by the EC.

About the steering committees:

  • STC: medInria Scientific and Technical Committee, defines the technical roadmap twice a year, validate the contribution rules, the Reviewers team and discuss every technical point in medInria.
  • EC: medInria Executive Committee, decides on evolution of the membership contract, the communication policy and the priorities of the Consortium.

Issues

For bug tracking, feature proposals and task management, create a medInria issue! Whatever issue you are having, you are likely not the only one, so others will find your issue helpful too. Issues labeled "Discussion" are also used for larger topics: architecture, future of medInria, long term dev, etc.

Please DO NOT create an issue for support. Consider reading the online help on the Github medInria Wiki to install prerequisites, known how to compile the software, or learn how to use it.

When creating an issue, pay attention to the following tips:

  • Check existing issues. What you are running into may have been addressed already.
  • Set the right label to your issue among our label list or propose them in the description.
  • Be clear about what your problem is: what was the expected outcome, what happened instead? Detail how someone else can recreate the problem.

For more information on issues, check out this GitHub guide.

Pull requests

If you are able to patch the bug or add the feature yourself – fantastic, make a Pull Request with the code! Be sure you have read any documents on contributing and you understand the medInria license. Once you have submitted a PR the maintainer(s) can compare your branch to the existing one and decide whether or not to incorporate (pull in) your changes.

Reminder - How to manage Pull Requests (from GitHub documentation)

Rules

  • Description must explain the problem solved or the feature added, and this must be reported in the RELEASE_NOTES.txt file if the changes are meaningful.
  • Code must follow our guidelines (not done yet).
  • Commit must build successfully on medInria integration system (Jenkins) for all steps: compilation + tests + examples.
  • Unit Tests are highly recommended for each new component or if an issue is fixed (as soon as the Unit Tests system is created in medInria, and the documentation to do it is done).

Lifecycle

Standard Pull Requests are reviewed and approved by the "Reviewers" team. Major PR (BREAKING, major features) are reviewed by the "Reviewers" team and approved by the "STC members" team through a vote within a maximum period of 2 weeks.

Reviewing:

  • Make sure the Pull Request has an appropriate title, description, and if needed milestone and labels.
  • Control that it follows our rules defined above.
  • Control the builds: Dashboard > Details, in the Pull Request "Checks" tab (if the system is installed).
  • Merge method: prefer "merge" or "squash" over "rebase".

Remember that:

  • You can add commits in a Pull Request: see GitHub documentation.
  • If the pull request contains out of scope commits (from a previous merge with master), consider rebasing it.