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 :
- Backbone: some MCAI-related tools configuration
- Backend: the MCAI Web platform sources
- Command Line Tools: some CLI applications to interact with the MCAI environment
- Continuous Integration: CI pipelines and runners definitions
- Documentation: for the MCAI Web Site
- Libraries: common libraries sources
- SDKs: Rust and Python SDKs for MCAI workers
- Startup: MCAI deployment utilities
- Workers: MCAI workers
To be defined
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 by anyone wishing to contribute to the Media-Cloud AI project.
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 (
develop, or both).
Branch naming rule:
Git branches should be named following this pattern:
ci… as possible
Here are some good practices to apply:
- Use English for all contributions
- Write descriptive and meaningful commit messages. No, “change” “wip” or “update” don’t belong to this category!
- Commit only related work: the least amount of lines that make sense together, and related to the branch purpose.
- Don’t commit changes that break the code: projects should be compiling at any commit level.
- The author of a commit is responsible for it and should try to fix issues it may cause.
- Rebase your working branch as frequently as you can before publishing it on the remote repository.
- Don’t push directly on main branches (master, main, develop…)
push --forceonto a main branch (master, main, develop), other developers are basing there work on it!
- You may rewrite the history (
push --force) in specific cases:
- After you rebased your branch
- To amend the last commit of your branch
Always make sure to explicit the target branch when using
Overall, avoid changing a published history! If you want to change your branch history:
- Create a new branch
- Re-commit your changes properly on the new branch (
git cherry-pickcan be helpful)
- Then remove the former branch
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.
Each contribution must be linked to an Issue on the related Gitlab repository.
This means that, as an example, if you found a bug:
- Check whether an Issue already exists regarding this bug
- 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
- Create a new branch with a name based on the title of the Issue (see the Branch naming rule section)
- Start commiting patches to fix this bug
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 (
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
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
To sum up:
- Find or create an Issue
- Create a related branch
- Commit properly: , project still compiling
- Push your branch
- Create a Merge Request (MR), and ask for a review
- Follow/discuss the comments of the reviewer, commit & push corrections
- Once the MR is approved, merge your branch into the target branch
- Congrats! You (or the issuer) may now close the related issue.