Skip to content
Snippets Groups Projects
develop.html 7.54 KiB
Newer Older
Cédric Krier's avatar
Cédric Krier committed
{% set title = "How to Develop" %}
{% set description = "How to develop for Tryton" %}
{% set keywords = ["development", "mercurial", "codereview", "patch" ] %}
Cédric Krier's avatar
Cédric Krier committed
{% set toc = [
    ("Submit a Change", 'submit-change', None),
    ("Guidelines", 'guidelines', [
        ("Code", 'guidelines-code', None),
        ("Documentation", 'guidelines-documentation', None),
        ("Commit Message", 'commit-message', None),
Cédric Krier's avatar
Cédric Krier committed
        ]),
    ("Requirements", 'requirements', None),
    ("Rules", 'rules', None),
Cédric Krier's avatar
Cédric Krier committed
    ("Roles", 'roles', None),
Cédric Krier's avatar
Cédric Krier committed
    ("Publish a Change", 'publish-change', None),
Cédric Krier's avatar
Cédric Krier committed
    ("Backporting", 'backporting', None),
    ]
%}
{% extends "layout-toc.html" %}
{% from "utils.html" import background with context %}
{% block style %}
{{ super() }}
{{ background('banner-develop') }}
{% endblock %}
{% block content %}
<section class="section section-banner background-banner-develop filter filter-primary text-center lazy">
    <div class="container">
        <h1 class="mb-0 text-white position-relative z-1">{{ title }}</h1>
    </div>
{{ super() }}
{% endblock content %}

{% block main %}
Cédric Krier's avatar
Cédric Krier committed
<div class="subsection">
    <p class="lead">
    <span class="h2">TL;DR</span><br/>
Cédric Krier's avatar
Cédric Krier committed
    Clone the repository:</p>
Cédric Krier's avatar
Cédric Krier committed
    <pre><code class="console">$ hg clone https://foss.heptapod.net/tryton/tryton
$ cd tryton
$ hg topic my-change</code></pre>
Cédric Krier's avatar
Cédric Krier committed
    <p class="lead">
Cédric Krier's avatar
Cédric Krier committed
    Make your modification.</p>
    <pre><code class="console">$ hg push</code></pre>
    <p class="lead">
    Click on the link to create the Merge Request.</p>
Cédric Krier's avatar
Cédric Krier committed
</div>
<div class="subsection">
    <h2 id="submit-change">Submit a Change</h2>
Cédric Krier's avatar
Cédric Krier committed
    <p class="bg-info rounded p-2">The project is using <a href="https://www.mercurial-scm.org/">mercurial</a> as Version Control System with the <a href="https://pypi.org/project/hg-evolve/">hg-evolve extension</a>.</p>
    <ul>
        <li>Follow the <a href="#guidelines">guidelines</a>.</li>
        <li><a href="https://foss.heptapod.net/tryton">Request access</a> to the project <i>(by clicking on the link next to the project title)</i>.</li>
Cédric Krier's avatar
Cédric Krier committed
        <li>Submit your change with a <a href="https://heptapod.net/pages/quick-start-guide.html">merge request</a> on <a href="https://foss.heptapod.net/tryton/tryton">our Heptapod instance</a>.</li>
        <li>Ensure you did not break the tests by running them and add tests if necessary.</li>
Cédric Krier's avatar
Cédric Krier committed
        <li>Once accepted your merge request is merged by a Mercurial Publisher.</li>
    </ul>
Cédric Krier's avatar
Cédric Krier committed
</div>
<div class="subsection">
    <h2 id="guidelines">Guidelines</h2>
    <p>The Tryton Project has guidelines for both code and documentation.</p>
    <h3 id="guidelines-code">Code</h3>
    <ul>
        <li>The <a href="{{ url_for('guidelines_code') }}">Coding Guidelines</a> should be followed for any review you submit.</li>
    </ul>
    <h3 id="guidelines-documentation">Documentation</h3>
    <p>
    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.</p>
    <p>So to avoid duplication, and keep the documentation organised and maintainable there are several sets of guidelines:</p>
    <ul>
        <li>When creating documentation for a package you should follow the main <a href="{{ url_for('guidelines_documentation') }}">Documentation Guidelines</a>.</li>
        <li>There are some <a href="{{ url_for('guidelines_documentation_help') }}">Help Text Guidelines</a> to follow if you are writing or changing help text.</li>
        <li>If submitting a Howto for approval, then please make sure you've followed the <a href="{{ url_for('guidelines_documentation_howto') }}">Howto Guidelines</a>.</li>
    </ul>
    <h3 id="commit-message">Commit Message</h3>
    <ul>
        <li>
            Use a short title starting with a capital letter.
            <ul>
                <li>Use imperative mood.<br/>
                    <em>So that it completes the sentence "With this change, the project will…".</em>
                </li>
                <li>
                    Use human names of objects instead of the technical name.<br/>
                    <em>Like "Invoice" instead of "account.invoice".</em>
                </li>
            </ul>
        </li>
        <li>Add extra details in the message body (optional).
            <ul>
                <li>Less than 80 characters per line.</li>
                <li>Explain <strong>WHAT</strong> the change is, but most importantly <strong>WHY</strong> the change is needed.</li>
                <li>Leave a blank line between the body and the title.</li>
                <li>Separate paragraphs in the body with blank lines.</li>
                <li>Use a hyphen (<samp>-</samp>) for bullet points if needed.</li>
                <li>Use hanging indents if needed.</li>
            </ul>
        </li>
        <li>Include the <a href="https://docs.gitlab.com/ee/user/project/issues/managing_issues.html#default-closing-pattern">pattern to close</a> linked issues (optional).</li>
    </ul>
Cédric Krier's avatar
Cédric Krier committed
</div>
<div class="subsection">
    <h2 id="requirements">Requirements</h2>
Cédric Krier's avatar
Cédric Krier committed
    <p>Your contribution must meet the following requirements:</p>
    <h3>Must</h3>
    <ul>
Cédric Krier's avatar
Cédric Krier committed
        <li>By submitting a change, the contributor accepts the <a href="https://developercertificate.org/">Developer Certificate of Origin</a>.</li>
        <li>The contributor email must be a valid email address.</li>
        <li>The domain of the contributor email must not contain tryton.</li>
Cédric Krier's avatar
Cédric Krier committed
        <li>The <span class="text-monospace">username</span> of a mercurial changeset must be in the form:
            <pre>Name &lt;email&gt;</pre>
        </li>
    </ul>
    <h3>Nice to have, but not required</h3>
    <ul>
        <li>The contributor name should be the real name of the natural person who submits the code.</li>
        <li>The contributor email should be linked to only one contributor name.</li>
    </ul>
Cédric Krier's avatar
Cédric Krier committed
</div>
<div class="subsection">
    <h2 id="rules">Rules</h2>
Cédric Krier's avatar
Cédric Krier committed
    <p>If the contributor has a significant amount of code, he can add himself to the <span class="text-monospace">COPYRIGHT</span> file of the modified packages.</p>
Cédric Krier's avatar
Cédric Krier committed
    In the case of disagreement, a consensus should be reached.
Cédric Krier's avatar
Cédric Krier committed
    As a last resort, the project leader (<a href="https://foss.heptapod.net/cedk">Cédric Krier</a>) will make the decision.
    </p>
Cédric Krier's avatar
Cédric Krier committed
</div>
<div class="subsection">
Cédric Krier's avatar
Cédric Krier committed
    <h2 id="roles">Roles</h2>
    <ul>
        <li>
            Developers can create merge requests.
        </li>
        <li>
            Mercurial Publishers can merge requests on default branch.
        </li>
        <li>
            Maintainers can push directly on all branches to make releases.
        </li>
    </ul>
</div>
<div class="subsection">
Cédric Krier's avatar
Cédric Krier committed
    <h2 id="publish-change">Publish a Change</h2>
Cédric Krier's avatar
Cédric Krier committed
    <p class="bg-info rounded p-2">This part is only for Mercurial Publishers</p>
Cédric Krier's avatar
Cédric Krier committed
    <p>
Cédric Krier's avatar
Cédric Krier committed
    Prefer publication without merge (fast-forward).
Cédric Krier's avatar
Cédric Krier committed
    </p>
Cédric Krier's avatar
Cédric Krier committed
    <p>
    Squash fix commits that the developer may have done instead of amending.
    </p>
    <p>
    Ensure commit message contains proper <a href="https://docs.gitlab.com/ee/user/project/issues/managing_issues.html#default-closing-pattern">pattern to close</a> linked issues.
    </p>
Cédric Krier's avatar
Cédric Krier committed
</div>
<div class="subsection">
Cédric Krier's avatar
Cédric Krier committed
    <h2 id="backporting">Backporting</h2>
Cédric Krier's avatar
Cédric Krier committed
    <p>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.</p>
    <p>Those rules don't apply for security bugs which are applied at once to all affected series and followed by a release.</p>
Cédric Krier's avatar
Cédric Krier committed
</div>
{% endblock main %}