Skip to content

Submitting your code

GitLab setup

  • In order to submit a patch to Callico's source code, you need to have a working GitLab setup and account on Teklia's GitLab instance, as explained in the "Clone the source code" section of the documentation.

Submitting a patch to Callico's source code

Find issues

We use GitLab to track issues (either bugs, or new features).

You can look at Callico's issues from different views:

  • through the current milestone, the most important issues are listed there, as they are the most time-sensitive
  • through the full issue list

Info

Please ask first if you can work on an issue, by simply commenting on it. Be aware that some issues may be way more complex than others.

Priorities

Issues should have a priority label:

  • P1 are high priority, usually bugs badly affecting users experience,
  • P2 are at the normal priority level
  • P3 are low priority

If nothing is set, assume P2 by default.

Work on a branch

To start working on a patch, you must first create a git branch, based on the current master branch:

# Start from master
git checkout master

# Update master to latest available revision
git pull origin master

# Create a new branch
git checkout -b my-new-branch

Each new commit will then be stored on that new branch named my-new-branch.

✅ To name your branch, use a name:

  1. in English,
  2. in lowercase,
  3. without spaces, use dashes - to link words,
  4. explicit and related to your current work.

Here are some examples of suitable branch names:

  • remove-model-x when the goal is to remove a Django model named X
  • fix-invalid-chars-search when the patch fixes a bug related to search
  • bump-dependency-y
  • add-super-feature
  • feature-z

❌ Please avoid:

  • naming your branch with the issue ID, we prefer explicit naming here,
  • using another language than English,
  • spaces, camelCase, underscores, etc.

Publish your work

You are allowed to push directly on Callico's repository, except for the master branch. The goal is for your code to reach master once the following steps are completed:

  1. Unit tests are all OK, meaning that all jobs in the CI stage named test ended in success. See the dedicated documentation here.
  2. Formatting has been validated by a tool, meaning that all jobs in the CI stage named checks ended in success. See the dedicated documentation here.
  3. The code itself has been approved by a human reviewer.

To get approvals, you need to create a Merge Request (also called MR) on GitLab.

When pushing your code from your local branch, you will notice some output in the console with a link towards gitlab.teklia.com: it will allow you to create a Merge Request (or view the previously created one) in 2 clicks.

Once your work is ready, configure your Merge Request as follows:

  • Assign yourself as the Assignee.
  • Assign @babadie as the Reviewer, he will either review or re-assign to another reviewer when needed.
  • Set an explicit Title, in English, properly formatted.
  • Add a reference to the issue you are working on in the Description:
    • Closes #XYZ if you fully solve the mentioned issue,
    • Ref #XYZ if you only want to link your Merge Request to the issue.
  • Fill in the Description with an explanation of the changes you made.
  • If the related issue has a milestone set, set the same Milestone on this Merge Request.

If you are not confident the work being published is yet ready for review, you can prefix your Merge Request title with Draft:; that will tell the reviewer to wait a bit before diving into your code. Do not forget to remove that prefix once your code is ready.

The reviewer may leave some comments directly on the Merge Request, asking you for updates. Please resolve all of them (or discuss them if you disagree), publish some commits fixing the issues, and then ask for a new review. Rinse and repeat until the reviewer approves and merges your code!

Update your branch

As other developers are working on Callico, sometimes features/bugfixes/etc will land on master while your Merge Request touches the same parts. You may get conflicts here and will need to solve them using a rebase.

Info

It is your responsibility, as a developer, to maintain your code in a mergeable state: no conflicts and up to date with the latest master.

To update using rebase, while working on your branch:

# Retrieve the latest updates from master
git fetch origin master

# Now the remote reference to origin/master has been updated, you can rebase on top of it
# Be aware that the local reference to master is not yet updated, it is only updated with git pull
git rebase origin/master

The git rebase operation will ask you to solve manually conflicts (if any). Please follow this guide or ask us for help if you are lost.

Landing your code

If you have reached this step, congratulations and many thanks! Your code has been approved and should already be merged, as that is the responsibility of the reviewer.

Your work will be shipped in the next Callico release along with latest features, bugfixes and other contributions.