Tryton Unconference Liège 2017 is coming!

Quick Start

Clone the repository:

$ hg clone https://hg.tryton.org/trytond
$ cd trytond

Make your modification to the code.

Submit your patch:

$ curl -L -o ~/.local/bin/upload.py https://codereview.tryton.org/static/upload.py
$ python ~/.local/bin/upload.py --oauth2

Easy Issue

In order to ease the introduction of newcomers to the project development there is a list of easy issues on the issue tracker. You can find them using the Show easy button on the issue tracker (Roundup)

Translating

The translation community shares the effort on the Tryton Pootle Server.

If your language doesn't exist yet, you can request its creation by opening an issue on the Tryton bug tracker.

Introduction

Submitting issue

  • Test your issue on the latest development version.
  • Create an issue in our issue tracker (Roundup).
  • Set the affected components on the issue.
  • Assign the issue to you (your username on Roundup) with a comment that you are working on it and you will provide a fix.

If it is a security issue, be careful to correctly set the type to security. This way, the issue will only be visible to the security team until its release.

Submitting codereview

  • Follow the Coding Guidelines.
  • Don't create codereview related to new feature during feature freeze.
  • Submit your patch to Rietveld (with the module name in front of the title).
  • The commit message will be the review subject (with module name) and the review description. The review description must contain a reference to the issue (issue1234). The reference of the review (example review10004567) will be automatically added to the commit message.
  • Once your review validated by a LGTM comment of a core developer, your contribution will be committed and pushed, you don't need to do anything else.
  • Close the codereview once your patch is applied: use the link Edit issue, then check Closed and validate with the Update Issue button.

If it is a security issue, be careful to mark the review as protected.

There are two options for uploading and working with Rietveld:

upload.py

One is using upload.py (see the help).

hgreview

The other and recommended one is using hgreview. Which simplifies, not only patch uploading but also testing.

To install it use:

$ pip install hgreview

Then you should enable the extension either in your ~/.hgrc or the repository-specific .hgrc:

[extensions]
hgreview =

[review]
server = https://codereview.tryton.org
oauth2 = True
send_email = True

Then you can upload your patch (do not commit before upload):

$ hg review -m "repository_name: Improve things a lot"

For non-trunk fixes append the series number to repository name.

You can get the issue ID:

$ hg review --id

In order to test this patch (or another one) you can simply get latest version from within the repository:

$ hg review --fetch -i <issue id>

Guidelines

The Tryton Project strongly recommends the following guidelines for code contributed to the Tryton framework and modules:

Code Style

Code style follows in general PEP 8

  • Use 4 spaces for indentation.
  • Avoid the usage of from M import *, except for the __init__.py of modules.
  • If unsure about PEP 8 conformity use pep8 to check the code (with option ignore=E123,E124,E126,E128)
  • Breaking lines: * Use 4 spaces per bracket pair. * Prefer parenthesis over backslash.

Naming of modules, classes, variables

  • A name should be as descriptive and as short as possible
  • Avoid unnecessary duplicate of names
  • Naming structure of a model or module must follow these rules:
    • First part left of the name is the general functioning of the module or model,
    • after this comes the less general name parts (= the more specific name parts) of the module or model
    • If you are unsure with naming, please request first on the mailing list or on the IRC channel #tryton
  • For modules and method names use underscore for separating the name parts
  • For naming classes use CamelCase

Requirements

Your contribution should meet the following requirements (according to the Vote results performed on 2010-07-05):

Must

  • All contributions must be licensed under the same license as the existing code, which is the GNU General Public License, version 3.
  • The contributor email must be a valid email address.
  • The domain of the contributor email must not contain tryton.
  • The username of a mercurial patch 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.

Core developers are people which have SSH access to the repositories. They are allowed to push small fixes without LGTM. Bigger fixes need approval an (LGTM) comment of another core developer. LGTM means Looks Good To Me, acronym is used while reviewing patches (example review6451002). Core developers are flagged as committer in their profile (example user12) and they can be distinguished on the bugtracker by their small Tryton logo (example issue4392).

For bigger fixes, in case of disagreement, a consensus should be reached. At last the project leader (Cédric) takes a decision.

Back port

The patch will be back ported to older series by the maintainer on his own discretion after 1 week in the development branch. 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 on all affected series followed a release.

For committers

Configuration

The username must be set in Mercurial configuration like this:

[ui]
username = Firstname Lastname <user@example.com>

The contributor email must be a valid email address. The domain of the contributor email must not contain "tryton".

Usage

Fetch the code

See development source code but replace http://hg.tryton.org/ by ssh://hg@hg.tryton.org/ like:

$ hg clone ssh://hg@hg.tryton.org/trytond

Use one of the ssh keys defined in your roundup's details.

Fix

Change the files to fix the issue.

Codereview

Submit a codereview.

Commit

Commit the fix into your local repository with an explicit message:

$ hg commit

Comment format:

Short comment

Long description
on multi-lines.

issue1234
review1234

For well formed and informative comments please have a look at writing good changeset comments

If it is a review from another contributor, import the patch from codereview:

$ hg import <url to diff>

Push

Push to the remote server:

$ hg push

Sometimes, when we try to push we got a failure because we create a new head on the server. It happens generally because we forgot to update the repository before committing.

Use 'rebase' instead of 'merge' Merge doesn't generate a good history so we re-base the changeset we just did on top of the head:

hg rebase -r <my new changeset>

Tips

Here are few tips to speed-up usage of the mercurial repositories:

  • Clone using --uncompressed option:

    $ hg clone --uncompressed http://hg.tryton.org/trytond
    
  • Use a local mirror: Keep a local clean repository that you update daily and work on local clone of this repository. You will update only once from the internet, others update will be local and fast. Using local clone doesn't waste space because it uses hard-link and is very fast.