How to Develop

TL;DR
Clone the repository:

$ hg clone https://foss.heptapod.net/tryton/tryton
$ cd tryton
$ hg topic my-change

Refer to the setup on README.

Make your modification.

$ hg commit
$ hg push -r my-change

Click on the link to create the Merge Request.

Submit a Change

The project is using mercurial as Version Control System with the hg-evolve extension.

  • Follow the guidelines.
  • Request access to the project (by clicking on the link next to the project title).
  • Submit your change with a merge request that you assign to yourself on our Heptapod instance.
  • Ensure you did not break the tests by running them and add tests if necessary.
  • Resolve all threads opened by reviewers.
  • Once accepted your merge request is merged by a Mercurial Publisher.

There is no need to rebase merge requests too often, even when there are conflicts, as this is often just for CHANGELOG entries.

To ease the review process, avoid pushing rebase and modifications at the same time. Prefer to use the Rebase button.

Guidelines

The Tryton Project has guidelines for both code and documentation.

Code

Documentation

There are several different places that Tryton documentation can be found. This is to make sure it is available in the right format, at the right time, for different use cases.

So to avoid duplication, and keep the documentation organised and maintainable there are several sets of guidelines:

Commit Message

  • Use a short title starting with a capital letter.
    • Use imperative mood.
      So that it completes the sentence "With this change, the project will…".
    • Use human names of objects instead of the technical name.
      Like "Invoice" instead of "account.invoice".
  • Add extra details in the message body (optional).
    • Less than 80 characters per line.
    • Explain WHAT the change is, but most importantly WHY the change is needed.
    • Leave a blank line between the body and the title.
    • Separate paragraphs in the body with blank lines.
    • Use a hyphen (-) for bullet points if needed.
    • Use hanging indents if needed.
  • Include the pattern to close linked issues (optional).

Requirements

Your contribution must meet the following requirements:

Must

  • By submitting a change, the contributor accepts the Developer Certificate of Origin.
  • The contributor email must be a valid email address.
  • The domain of the contributor email must not contain tryton.
  • The username of a mercurial changeset must be in the form:
    Name <email>

Nice to have, but not required

  • The contributor name should be the real name of the natural person who submits the code.
  • The contributor email should be linked to only one contributor name.

Rules

If the contributor has a significant amount of code, he can add himself to the COPYRIGHT file of the modified packages.

In the case of disagreement, a consensus should be reached. As a last resort, the project leader (Cédric Krier) will make the decision.

Roles

  • Developers can create merge requests.
  • Mercurial Publishers can merge requests on default branch.
  • Maintainers can push directly on all branches to make releases.

Publish a Change

This part is only for Mercurial Publishers

Prefer publication without merge (fast-forward).

Squash fix commits that the developer may have done instead of amending.

Ensure commit message contains proper pattern to close linked issues.

Backporting

A fix will be back ported to older series by the maintainer on his own discretion using a backport merge request. The decision is based on the importance of the bug, the availability of workaround and the feasibilities.

Those rules don't apply for security bugs which are applied at once to all affected series and followed by a release.