CONTRIBUTING.md 7.97 KB
Newer Older
David Thompson's avatar
David Thompson committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42
Contributing to CMB
========================

This page documents at a very high level how to contribute to CMB.
Please check our [developer instructions][] for a more detailed guide to
developing and contributing to the project, and our [CMB Git README][]
for additional information.

The CMB development cycle is built upon the following components:

1. [Issues][] identify any issues including bugs and feature requests. In
   general, every code change should have an associated issue which identifies
   the bug being fixed or the feature being added.

2. [Merge Requests][] are collections of changes that address issues.

3. [Labels][] are labels or tags that can be added and removed to/from issues
   and/or merge requests to annotate them including indicating their state in
   the development cycle. See [Labels Glossary][].

4. [Milestones][] refer to development milestones such as numbered public
   releases, or named internal releases.

Reporting Issues
================

If you have a bug report or a feature request for CMB, you can use the
[issues][] tracker to report a [new issue][].

To report an issue.

1.  Register for an account on [our GitLab instance][GitLab Access]  and select a user name.

2. Create a [new issue][].

3. Ensure that the  issue has a **Title** and **Description**
   with enough details for someone from the development team to reproduce the
   issue. See [Gitlab Markdown] guide for styling the **Description**. Include
   screenshots and sample datasets whenever possible. Typically, reporter
   **should not** set any other fields for the issue, including
   **Assignee**, **Milestone**, or **Labels**. These get set by members of the
   development team.
43

David Thompson's avatar
David Thompson committed
44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114
4. If developers need more information on an issue, they will add the
   `triage:needinfo` label as add a comment for the reporter soliciting more
   information. Once the reporter has provided the necessary information, he or she
   should remove the `triage:needinfo` label from the issue to notify the
   development team.

When a developer starts working on an issue, the developer will add the
`workflow:active-development` label. Once the development is complete and the issue
resolved, the issue will be closed, and the `workflow:active-development` label
will be replaced by `workflow:customer-review`. At that point, the reporter can
checkout the latest `master` and confirm that the issue has been addressed. If so,
the reporter can remove the `workflow:customer-review` label. If the issue was not
addressed then the reporter should reopen the issue or solicit more information
from the developer by adding the `triage:needinfo` label.

To keep the number of open issues manageable, we will periodically expire old issues
with no activity. Such issues will be closed and tagged with the label
`triage:expired`. Such issues can be reopened if needed.

Notes for Project Managers
--------------------------

For every issue, project managers can assign:

1. **Milestone** to indicate which release this issue fix is planned for.
2. `priority:...` label to indicate how critical is this issue for the specific
   milestone, ranging from `priority:required`, `priority:important`,
   `priority:nice-to-have`, and `priority:low`. Only one priority label makes
   sense at a time.

Notes for Developers
--------------------

For every issue, developers can assign:

1. `area:...` labels to indicate which area this issue relates to in terms of the software process e.g. `area:build`,
   `area:doc`, etc.
2. `app:...` label to indicate which application is effected by  this issue. An issue
   may have multiple apps associated with it (or use `app:framework` to indicate this is a general issue effecting all CMB applications.
3. `triage:...` labels to indicate issue triage status. `triage:confirmed` is added
    when the issue has been confirmed. `triage:easy` is added for issues that are
    easy to fix. `triage:feature` is added to issues that are new feature requests.
    `triage:needinfo` is added to solicit more information from the reporter.
4. `triage:needinfo` label on closed issues means the reporter or reviewer is
    requesting more information from the developer before the fix can be reviewed.
    Please provide such information and then remove the label.
5. `workflow:active-development` label should be added to issues under development.


Fixing Issues
=============

Typically, one addresses issues by writing code. To start contributing to CMB:

1.  Register for an account on [our GitLab instance][GitLab Access]  and select a user name.

2.  [Fork CMB][] into your user's namespace on GitLab.

3.  Create a local clone of the main CMB repository. Optionally configure
    Git to [use SSH instead of HTTPS][].
    Then clone:

        $ git clone --recursive https://gitlab.kitware.com/cmb/cmb.git CMB
        $ cd CMB
    The main repository will be configured as your `origin` remote.

    For more information see: [Setup][] and [download instructions][]

4.  Run the [developer setup script][] to prepare your CMB work
    tree and create Git command aliases used below:

115
        $ ./util/SetupForDevelopment.sh
David Thompson's avatar
David Thompson committed
116
    This will prompt for your GitLab user name and configure a remote
117
    called `gitlab` to refer to it.
David Thompson's avatar
David Thompson committed
118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137

    For more information see: [Setup][]

5.  [Build CMB] and run it.

6.  Edit files and create commits (repeat as needed):

        $ edit file1 file2 file3
        $ git add file1 file2 file3
        $ git commit

    Commit messages must be thorough and informative so that
    reviewers will have a good understanding of why the change is
    needed before looking at the code. Appropriately refer to the issue
    number, if applicable.

    For more information see: [Create a Topic][]

7.  Push commits in your topic branch to your fork in GitLab:

138
        $ git push gitlab HEAD
David Thompson's avatar
David Thompson committed
139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165

    For more information see: [Share a Topic][]

8.  Run tests with ctest, or use the dashboard

9.  Visit your fork in GitLab, browse to the "**Merge Requests**" link on the
    left, and use the "**New Merge Request**" button in the upper right to
    create a Merge Request.

    For more information see: [Create a Merge Request][]

8.  Follow the [review][] process to get your merge request reviewed and tested.
    On success, the merge-request can be merged and closed.

    For more information see: [Review a Merge Request][]

9.  When a merge request is closed, any related issue should be closed (if not
    closed automatically) and assigned the `workflow:customer-review` label to
    request a review from the reporter.

10. Monitor the related issue for any `triage:needinfo` label additions to provide
    the customer with any details necessary to test the fix.

Our [wiki][] is used to document features, flesh out designs and host other
documentation. We have several [mailing lists][] to coordinate development and
to provide support.

166 167
[CMB Git README]: doc/dev/README.md
[developer instructions]: doc/dev/develop.md
David Thompson's avatar
David Thompson committed
168 169
[GitLab Access]: https://gitlab.kitware.com/users/sign_in
[Fork CMB]: https://gitlab.kitware.com/cmb/cmb/forks/new
170 171
[use SSH instead of HTTPS]: doc/dev/download.md#use-ssh-instead-of-https
[download instructions]: doc/dev/download.md#clone
David Thompson's avatar
David Thompson committed
172
[developer setup script]: Utilities/SetupForDevelopment.sh
173
[Setup]: doc/dev/develop.md#Setup
174
[Build CMB]: doc/dev/build.md
175 176 177 178 179
[Create a Topic]: doc/dev/develop.md#create-a-topic
[Share a Topic]: doc/dev/develop.md#share-a-topic
[Create a Merge Request]: doc/dev/develop.md#create-a-merge-request
[Review a Merge Request]: doc/dev/develop.md#review-a-merge-request
[review]: doc/dev/develop.md#review-a-merge-request
David Thompson's avatar
David Thompson committed
180 181 182 183 184 185 186 187
[Issues]: https://gitlab.kitware.com/cmb/cmb/issues
[Merge Requests]: https://gitlab.kitware.com/cmb/cmb/merge_requests
[Labels]: https://gitlab.kitware.com/cmb/cmb/labels
[Milestones]: https://gitlab.kitware.com/cmb/cmb/milestones
[Wiki]: https://gitlab.kitware.com/cmb/cmb/wikis/pages
[Mailing Lists]: http://www.computationalmodelbuilder.org/mailinglist/
[Gitlab Markdown]: https://gitlab.kitware.com/help/user/markdown.md
[new issue]: https://gitlab.kitware.com/cmb/cmb/issues/new
188
[Labels Glossary]: doc/dev/labels.md