Open source

The Media-Cloud AI source code is hosted on the https://gitlab.com/media-cloud-ai Gitlab group.

The project is organised arround the following subgroups :

Bug reports

To be defined

Code contribution

Feel free to propose your fix, improvement or feature in the code of any of the projects of Media-Cloud AI.

See the Developer contribution rules section to find out how to proceed.

Developer contribution rules

This document aims to define some rules that must be followed as strictly as possible by anyone wishing to contribute to the Media-Cloud AI project.

Git

As the main tool for sharing Media-Cloud AI code, the use of Git must be given special attention.

The organization of the different Git projects of Media-Cloud AI is based on the git-flow philosophy. This mainly involves that each contribution (feature, fix, hotfix or release) has its own branch, based on a main branch (main (formerly master) or develop, or both).

Branch naming rule:

Git branches should be named following this pattern:

`<topic>/<issue_title_or_description>`

with fix, feature, hotfix, release, ci… as possible <topic> values.

Commit policy:

Here are some good practices to apply:

Push consideration:

Overall, avoid changing a published history! If you want to change your branch history:

  1. Create a new branch
  2. Re-commit your changes properly on the new branch (git cherry-pick can be helpful)
  3. Then remove the former branch

Gitlab environment

The Gitlab platform is used to centralize the code, and to manage to development of Media-Cloud AI.

Before starting your contribution, please ensure your Gitlab profile shares the email address you configured in your local Git.

Issues:

Each contribution must be linked to an Issue on the related Gitlab repository.

This means that, as an example, if you found a bug:

  1. Check whether an Issue already exists regarding this bug
  2. If necessary, create a new Issue to report the bug a. Choose an explicit title b. Explicit the Issue into the description c. Don’t hesitate to split the Issue into multiple unit tasks d. Apply the appropiate labels
  3. Create a new branch with a name based on the title of the Issue (see the Branch naming rule section)
  4. Start commiting patches to fix this bug

Merge Requests:

Each contribution must result in a Merge Request on the related Gitlab repository. Each Merge Request must be related to an existing Issue.

When your development is complete, push your branch on the remote Gitlab repository, and create a Merge Request targeting a main branch (develop or main).

You must assign yourself as an Assignee: meaning that you are responsible for the changes proposed, and you will be in charge of merging the branch into the target branch.

You can mark the Merge Request as Draft, if you consider it is not ready for a review.

You can also use labels to improve the Merge Request understanding and indexation.

When the Merge Request is ready, you have to request a review by assigning the issuer or a relevant* developer as a Reviewer: this person has to review your code, may request some changes, and is responsible for the final approval.

You should also check the Continuous Integration (CI) pipeline results: all CI jobs must have succeeded before your branch can be merged.

Please be sure to have your branch rebased on the target branch in order to have the correct commit history. In addition, you should rebase your own commits so the commit history keeps clean and clear (eg. remove the wip or fix commits).

Once the Merge Request is approved (and the CI pipeline succeeded), you can merge your branch into the target branch.

Finally, you can close the related issue.

* someone that will be able to understand the purpose of your Merge Request, or at least a member of the Q&A team (if any)

Roadmap, Milestones and release management

Upstream of any new release, a roadmap will be determined by project owners with the content of this new release.

When all the features contained in the milestone are ready, a release branch is created from the develop branch and a release candidate version is tagged from it. Possibly, fixes are pushed in this release branch followed by another release candidate version.

When the release candidate is compliant to what is expected, the release branch is merged in both main and develop branches.


To sum up:

  1. Find or create an Issue
  2. Create a related branch
  3. Commit properly: explicit labels, project still compiling
  4. Push your branch
  5. Create a Merge Request (MR), and ask for a review
  6. Follow/discuss the comments of the reviewer, commit & push corrections
  7. Once the MR is approved, merge your branch into the target branch
  8. Congrats! You (or the issuer) may now close the related issue.