CONTRIBUTING.md 15.9 KB
Newer Older
1
# Contributing to VTK-m #
2

3
This page documents how to develop VTK-m through [Git](http://git-scm.com).
4

5
Git is an extremely powerful version control tool that supports many
6 7 8 9
different "workflows" for individual development and collaboration. Here we
document procedures used by the VTK-m development community. In the
interest of simplicity and brevity we do *not* provide an explanation of
why we use this approach.
10 11


12
## Setup ##
13 14 15

Before you begin, perform initial setup:

16
1.  Register [GitLab Access] to create an account and select a user name.
17

18
2.  [Fork VTK-m] into your user's namespace on GitLab.
19

20
3.  Use Git to create a local clone of the main VTK repository:
21

22
        $ git clone https://gitlab.kitware.com/vtk/vtk-m.git
23
        $ cd vtk-m
24

25 26
    The main repository will be configured as your `origin` remote.

27
4.  Run the developer setup script to prepare your VTK-m work tree and
28 29 30 31 32 33 34
    create Git command aliases used below:

        $ ./Utilities/SetupForDevelopment.sh

    This will prompt for your GitLab user name and configure a remote
    called `gitlab` to refer to it.

35 36 37 38 39 40
5. (Optional but highly recommended.) 
    [Register with the VTK-m dashboard] on Kitware's CDash instance to
    better know how your code performs in regression tests. After
    registering and signing in, click on "All Dashboards" link in the upper
    left corner, scroll down and click "Subscribe to this project" on the
    right of VTK-m.
41

42 43 44
6.  (Optional but highly recommended.) 
    [Sign up for the VTK-m mailing list] to communicate with other
    developers and users.
45

46 47
[GitLab Access]: https://gitlab.kitware.com/users/sign_in
[Fork VTK-m]: https://gitlab.kitware.com/vtk/vtk-m/forks/new
48 49 50
[Register with the VTK-m dashboard]: https://open.cdash.org/register.php
[Sign up for the VTK-m mailing list]: http://vtk.org/mailman/listinfo/vtkm

51

52
## Workflow ##
53

54 55
VTK-m development uses a [branchy workflow] based on topic branches. Our
collaboration workflow consists of three main steps:
56 57

1.  Local Development:
58 59
      * [Update](#update)
      * [Create a Topic](#create-a-topic)
60

61 62 63 64 65 66
2.  Code Review (requires [GitLab Access]):
      * [Share a Topic](#share-a-topic)
      * [Create a Merge Request](#create-a-merge-request)
      * [Review a Merge Request](#review-a-merge-request)
      * [Reformat a Topic](#reformat-a-topic)
      * [Revise a Topic](#revise-a-topic)
67 68

3.  Integrate Changes:
69
      * [Merge a Topic](#merge-a-topic) (requires permission in GitLab)
70 71 72

[branchy workflow]: http://public.kitware.com/Wiki/Git/Workflow/Topic

73 74

## Update ##
75 76

1.  Update your local `master` branch:
77

78 79
        $ git checkout master
        $ git pull
80

81
2.  Optionally push `master` to your fork in GitLab:
82

83 84 85
        $ git push gitlab master


86 87 88 89 90
## Create a Topic ##

All new work must be committed on topic branches. Name topics like you
might name functions: concise but precise. A reader should have a general
idea of the feature or fix to be developed given just the branch name.
91 92 93 94 95 96 97 98 99 100

1.  To start a new topic branch:

        $ git fetch origin

2.  For new development, start the topic from `origin/master`:

        $ git checkout -b my-topic origin/master

3.  Edit files and create commits (repeat as needed):
101 102 103 104 105

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

106
    Caveats:
107 108 109
      * Data files must be placed under a folder explicitly named 'data'.
        This is required as VTK-m uses Git-LFS to efficiently support data
        files.
110 111


112
### Guidelines for Commit Messages ###
113

114 115 116
Remember to *motivate & summarize*. When writing commit messages. Get into
the habit of creating messages that have enough information for any
developer to read and glean relevant information such as:
117 118 119 120 121 122

1.  Is this change important and why?
2.  If addressing an issue, which issue(s)?
3.  If a new feature, why is it useful and/or necessary?
4.  Are there background references or documentation?

123 124 125 126 127 128 129
A short description of what the issue being addressed and how will go a
long way towards making the log more readable and the software more
maintainable. VTK-m requires that your message start with a single subject
line, followed by a blank line, followed by the message body which contains
the more detailed explanatory text for the commit. You can consider a
commit message to very similar to an email with the first line being the
subject of an email and the rest of the text as the body.
130

131
Style guidelines for commit messages are as follows:
132

133 134 135 136 137 138 139 140 141
1.   Separate subject from body with a blank line
2.   Limit the subject line to 78 characters
3.   Capitalize the subject line
4.   Use the imperative mood in the subject line e.g. "Refactor foo" or
     "Fix Issue #12322", instead of "Refactoring foo", or "Fixing issue
     #12322".
5.   Wrap the body at 80 characters
6.   Use the body to explain `what` and `why` and if applicable a brief
    `how`.
142 143


144 145 146 147 148 149 150
## Share a Topic ##

When a topic is ready for review and possible inclusion, share it by
pushing to a fork of your repository in GitLab. Be sure you have registered
and signed in for [GitLab Access] and created your fork by visiting the
main [VTK-m GitLab] repository page and using the "Fork" button in the
upper right.
151 152 153 154 155 156 157 158

[VTK-m GitLab]: https://gitlab.kitware.com/vtk/vtk-m

1.  Checkout the topic if it is not your current branch:

        $ git checkout my-topic

2.  Push commits in your topic branch to your fork in GitLab:
159

160
        $ git gitlab-push
161

162
    Notes:
163 164 165 166 167 168 169 170
      * If you are revising a previously pushed topic and have rewritten
        the topic history, add `-f` or `--force` to overwrite the
        destination.
      * The `gitlab-push` script also pushes the `master` branch to your
        fork in GitLab to keep it in sync with the upstream `master`.

    The output will include a link to the topic branch in your fork in
    GitLab and a link to a page for creating a Merge Request.
171 172


173
## Create a Merge Request ##
174

175 176
When you [pushed your topic branch](#share-a-topic), it will provide you
with a url of the form
177

178
    https://gitlab.kitware.com/<username>/vtk-m/merge_requests/new
179

180 181 182 183 184 185 186
You can copy/paste that into your web browser to create a new merge
request. Alternately, you can 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.

Once at the create merge request page, follow these steps. Many of these
will be filled out for you.
187 188 189 190 191

1.  In the "**Source branch**" box select the `<username>/vtk-m` repository
    and the `my-topic` branch.

2.  In the "**Target branch**" box select the `vtk/vtk-m` repository and
192
    the `master` branch. It should be the default.
193

194 195
3.  Use the "**Compare branches**" button to proceed to the next page and
    fill out the merge request creation form.
196 197

4.  In the "**Title**" field provide a one-line summary of the entire
198
    topic. This will become the title of the Merge Request.
199 200 201 202 203

    Example Merge Request Title:

        Add OpenMP Device Adapter

204 205 206
5.  In the "**Description**" field provide a high-level description of the
    change the topic makes and any relevant information about how to try
    it. 
207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225
    *   Use `@username` syntax to draw attention of specific developers.
        This syntax may be used anywhere outside literal text and code
        blocks.  Or, wait until the [next step](#review-a-merge-request)
        and add comments to draw attention of developers.
    *   Optionally use a fenced code block with type `message` to specify
        text to be included in the generated merge commit message when the
        topic is [merged](#merge-a-topic).

    Example Merge Request Description:

        This branch adds a new device adapter that uses new OpenMP 4+ features
        including Task groups to better handle unbalanced and irregular domains

        ```message
        Add a OpenMP 4+ task-based device adapter.
        ```

        Cc: @user1 @user2

226 227
6.  The "**Assign to**", "**Milestone**", and "**Labels**" fields may be
    left blank.
228 229 230 231

7.  Use the "**Submit merge request**" button to create the merge request
    and visit its page.

232
### Guidelines for Merge Requests ###
233

234 235 236
Remember to *motivate & summarize*. When creating a merge request, consider
the reviewers and future perusers of the software. Provide enough
information to motivate the merge request such as:
237 238 239 240 241 242

1.  Is this merge request important and why?
2.  If addressing an issue, which issue(s)?
3.  If a new feature, why is it useful and/or necessary?
4.  Are there background references or documentation?

243 244 245 246
Also provide a summary statement expressing what you did and if there is a
choice in implementation or design pattern, the rationale for choosing a
certain path. Notable software or data features should be mentioned as
well.
247

248 249 250 251 252 253
A well written merge request will motivate your reviewers, and bring them
up to speed faster. Future software developers will be able to understand
the reasons why something was done, and possibly avoid chasing down dead
ends, Although it may take you a little more time to write a good merge
request, you’ll likely see payback in faster reviews and better understood
and maintainable software.
254 255


256
## Review a Merge Request ##
257 258

Add comments mentioning specific developers using `@username` syntax to
259 260 261
draw their attention and have the topic reviewed. After typing `@` and some
text, GitLab will offer completions for developers whose real names or user
names match.
262

263 264 265
Comments use [GitLab Flavored Markdown] for formatting. See GitLab
documentation on [Special GitLab References] to add links to things like
merge requests and commits in other repositories.
266 267 268 269 270 271 272 273 274 275 276

[GitLab Flavored Markdown]: https://gitlab.kitware.com/help/markdown/markdown
[Special GitLab References]: https://gitlab.kitware.com/help/markdown/markdown#special-gitlab-references

### Reviews ###

Reviewers may add comments providing feedback or to acknowledge their
approval. All comments use the [GitLab Flavored Markdown][], any line of a
comment may be exactly one of the following votes followed by nothing but
whitespace before the end of the line:

277 278
  * `-1` or :-1: (`:-1:`) means "The change is not ready for integration."
  * `+1` or :+1: (`:+1:`) means "The change is ready for integration."
279 280

These are used to inform the author that a merge srequest has been approved
281
for [merging](#merge-a-topic).
282

283
#### Fetching Changes ####
284

285 286 287
One may fetch the changes associated with a merge request by using the `git
fetch` command line shown at the top of the Merge Request page. It is of
the form:
288 289 290 291 292 293 294

    $ git fetch https://gitlab.kitware.com/$username/vtk-m.git $branch

This updates the local `FETCH_HEAD` to refer to the branch.

There are a few options for checking out the changes in a work tree:

295
  * One may checkout the branch:
296 297

        $ git checkout FETCH_HEAD -b $branch
298

299 300 301 302
    or checkout the commit without creating a local branch:

        $ git checkout FETCH_HEAD

303
  * Or, one may cherry-pick the commits to minimize rebuild time:
304 305 306 307 308

        $ git cherry-pick ..FETCH_HEAD

### Robot Reviews ###

309 310 311 312
The "Kitware Robot" automatically performs basic checks on the commits and
adds a comment acknowledging or rejecting the topic. This will be repeated
automatically whenever the topic is updated. A re-check may be explicitly
requested by adding a comment with a single *trailing* line:
313 314 315 316 317 318 319 320

    Do: check

A topic cannot be [merged](#merge-a-topic) until the automatic review
succeeds.

### Testing ###

321 322 323 324 325
VTK-m has a [buildbot](http://buildbot.net) instance watching for merge
requests to test. Each time a merge request is updated the buildbot user
(@buildbot) will automatically trigger a new build on all VTK-m buildbot
workers. The buildbot user (@buildbot) will respond with a comment linking
to the CDash results when it schedules builds.
326

327 328
The buildbot user (@buildbot) will also respond to any comment with the
form:
329 330 331 332 333

    Do: test

The `Do: test` command accepts the following arguments:

334 335 336 337
  * `--oneshot` 
        only build the *current* hash of the branch; updates will not be
        built using this command
  * `--stop` 
338
        clear the list of commands for the merge request
339
  * `--superbuild` 
340
        build the superbuilds related to the project
341
  * `--clear` 
342
        clear previous commands before adding this command
343 344 345 346
  * `--regex-include <arg>` or `-i <arg>` 
        only build on builders matching `<arg>` (a Python regular
        expression)
  * `--regex-exclude <arg>` or `-e <arg>` 
347 348 349
        excludes builds on builders matching `<arg>` (a Python regular
        expression)

350 351 352
Multiple `Do: test` commands may be given in separate comments. Buildbot
may skip tests for older branch updates that have not started before a test
for a new update is requested.
353

354
Build names always follow this pattern:
355

356
        SHA-build#-[os-libtype-buildtype+feature1+feature2]-topic
357

358 359
  * SHA: The shortened 8-digit SHA identifying the git commit being tested
  * build: `build####` with `####` replaced by a unique number for the build
360 361 362 363
  * os: one of `windows`, `osx`, or `linux`
  * libtype: `shared` or `static`
  * buildtype: `release` or `debug`
  * feature: alphabetical list of features enabled for the build
364
  * topic: the git topic branch being tested
365 366


367
## Reformat a Topic ##
368

369 370 371 372 373
The "Kitware Robot" automatically performs basic code formatting on the
commits and adds a comment acknowledging or rejecting a merge request based
on the format. You may request "Kitware Robot" to automatically reformat
the remote copy of your branch by issuing the following command in a merge
request page comment:
374 375 376 377 378

    Do: reformat

This reformatting of the topic rewrites the commits to fix the formatting
errors, and causes the version on the developers machine to differ from
379 380 381
version on the gitlab server. To resolve this issue you must update the
local version to match the reformatted one on the server if you wish to
extend or revise the topic.
382 383 384 385 386 387 388 389 390 391

1.  Checkout the topic if it is not your current branch:
        $ git checkout my-topic

2.  Get the new version from gitlab

        $ git gitlab-sync -f


If you do not wish to have the "Kitware Robot" automatically reformat your
392 393 394
branch you can do so manually by running [clang-format] manually on each
commit of your branch. This must be done by [revising each
commit](#revise-a-topic) not as new commits onto the end of the branch.
395

396
[clang-format]: https://clang.llvm.org/docs/ClangFormat.html
397

398

399 400 401 402 403 404 405 406 407 408 409
## Revise a Topic ##

Revising a topic is a special way to modify the commits within a topic.
Normally during a review of a merge request a developer will resolve issues
brought up during review by adding more commits to the topic. While this is
sufficient for most issues, some issues can only be resolved by rewriting
the history of the topic.

If a reviewer has asked explicitly for certain commits to be rewritten, you
will need to revise the commits and force push it back to GitLab for
another review. To revise a topic for another review as follows:
410 411 412 413 414 415 416 417 418

1.  Checkout the topic if it is not your current branch:

        $ git checkout my-topic

2.  To revise the `3`rd commit back on the topic:

        $ git rebase -i HEAD~3

419 420
    (Substitute the correct number of commits back, as low as `1`.) Follow
    Git's interactive instructions.
421

422 423 424 425 426
3.  Push commits in your topic branch to your fork in GitLab:

        $ git gitlab-push -f

    Notes:
427 428 429
      * You need to add `-f` or `--force` to overwrite the destination as
        you are revising a previously pushed topic and have rewritten the
        topic history.
430

431
## Merge a Topic ##
432 433

After a topic has been reviewed and approved in a GitLab Merge Request,
434
authorized developers may add a comment with a single *trailing* line:
435 436 437

    Do: merge

438
to ask that the change be merged into the upstream repository. By
luz.paz's avatar
luz.paz committed
439
convention, only merge if you have received `+1` . Do not request a merge
440
if any `-1` review comments have not been resolved.
441 442 443 444 445 446 447 448 449

### Merge Success ###

If the merge succeeds the topic will appear in the upstream repository
`master` branch and the Merge Request will be closed automatically.

### Merge Failure ###

If the merge fails (likely due to a conflict), a comment will be added
450
describing the failure. In the case of a conflict, fetch the latest
451 452 453 454 455 456
upstream history and rebase on it:

    $ git fetch origin
    $ git rebase origin/master

Return to the [above step](#share-a-topic) to share the revised topic.