develop.md 12.1 KB
Newer Older
1
2
Develop ParaView with Git
=========================
3

4
This page documents how to develop ParaView through [Git][].
5
6
7
8
9
10
See the [README](README.md) for more information.

[Git]: http://git-scm.com

Git is an extremely powerful version control tool that supports many
different "workflows" for individual development and collaboration.
11
Here we document procedures used by the ParaView development community.
12
13
14
15
16
17
18
19
In the interest of simplicity and brevity we do *not* provide an
explanation of why we use this approach.

Setup
-----

Before you begin, perform initial setup:

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

22
2.  [Fork ParaView][] into your user's namespace on GitLab.
23

24
3.  Follow the [download instructions](download.md#clone) to create a
25
26
27
    local clone of the main ParaView repository.  Optionally configure
    Git to [use SSH instead of HTTPS](download.md#use-ssh-instead-of-https).
    Then clone:
28

29
        $ git clone --recursive https://gitlab.kitware.com/paraview/paraview.git ParaView
30
        $ cd ParaView
31
    The main repository will be configured as your `origin` remote.
32

33
4.  Run the [developer setup script][] to prepare your ParaView work tree and
34
35
36
    create Git command aliases used below:

        $ ./Utilities/SetupForDevelopment.sh
37
38
    This will prompt for your GitLab user name and configure a remote
    called `gitlab` to refer to it.
39

40
5.  (Optional but highly recommended.)
41
    [Register](https://open.cdash.org/register.php) with the ParaView project
42
43
44
    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
45
    "Subscribe to this project" on the right of ParaView.
46
47

[GitLab Access]: https://gitlab.kitware.com/users/sign_in
48
[Fork ParaView]: https://gitlab.kitware.com/paraview/paraview/fork/new
49
50
51
52
53
[developer setup script]: /Utilities/SetupForDevelopment.sh

Workflow
--------

54
ParaView development uses a [branchy workflow][] based on topic branches.
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
Our collaboration workflow consists of three main steps:

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

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)
    * [Revise a Topic](#revise-a-topic)

3.  Integrate Changes:
    * [Merge a Topic](#merge-a-topic) (requires permission in GitLab)
    * [Delete a Topic](#delete-a-topic)

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

Update
------

1.  Update your local `master` branch:

        $ git checkout master
79
        $ git pullall
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100

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.

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

    For release branch fixes, start the topic from `origin/release`, and
    by convention use a topic name starting in `release-`:

        $ git checkout -b release-my-topic origin/release

101
102
103
104
    If subdmodules may have changed, the  run:

        $ git submodule update

105
106
107
108
109
110
111
3.  Edit files and create commits (repeat as needed):

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

    Caveats:
112
113
    * To add data follow [these instructions](https://gitlab.kitware.com/vtk/vtk/blob/master/Documentation/dev/git/data.md),
      from VTK.
114
115
116
117
118
119
120

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
121
[ParaView GitLab][] repository page and using the "Fork" button in the upper right.
122

123
[ParaView GitLab]: https://gitlab.kitware.com/paraview/paraview
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139

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

        $ git checkout my-topic

2.  Check what commits will be pushed to your fork in GitLab:

        $ git prepush

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

        $ git gitlab-push

    Notes:
    * If you are revising a previously pushed topic and have rewritten the
      topic history, add `-f` or `--force` to overwrite the destination.
140
    * If the topic adds data see [this note](https://gitlab.kitware.com/vtk/vtk/blob/master/Documentation/dev/git/data.md#push).
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155

    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.

Create a Merge Request
----------------------

(If you already created a merge request for a given topic and have reached
this step after revising it, skip to the [next step](#review-a-merge-request).)

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
reach the URL printed at the end of the [previous step](#share-a-topic).
It should be of the form:

156
    https://gitlab.kitware.com/<username>/paraview/merge_requests/new
157
158
159

Follow these steps:

160
1.  In the "**Source branch**" box select the `<username>/paraview` repository
161
162
    and the `my-topic` branch.

163
2.  In the "**Target branch**" box select the `paraview/paraview` repository and
164
165
166
167
168
169
    the `master` branch.  It should be the default.

    If your change is a fix for the `release` branch, you should still
    select the `master` branch as the target because the change needs
    to end up there too.

170
171
3.  Use the "**Compare branches**" button to proceed to the next page
    and fill out the merge request creation form.
172

173
174
175
176
177
178
4.  In the "**Title**" field provide a one-line summary of the entire
    topic.  This will become the title of the Merge Request.

    Example Merge Request Title:

        Wrapping: Add Java 1.x support
179
180
181

5.  In the "**Description**" field provide a high-level description
    of the change the topic makes and any relevant information about
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
    how to try it.
    *   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.
    *   If your change is a fix for the `release` branch, indicate this
        so that a maintainer knows it should be merged to `release`.
    *   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 requires Java 1.x which is not generally available yet.
        Get Java 1.x from ... in order to try these changes.
197
198

        ```message
199
        Add support for Java 1.x to the wrapping infrastructure.
200
201
        ```

202
203
204
205
206
207
208
        Cc: @user1 @user2

6.  The "**Assign to**", "**Milestone**", and "**Labels**" fields
    may be left blank.

7.  Use the "**Submit merge request**" button to create the merge request
    and visit its page.
209
210
211
212
213

Review a Merge Request
----------------------

Add comments mentioning specific developers using `@username` syntax to
214
215
216
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.
217

218
219
220
221
222
223
224
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.

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

225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
### Human Reviews ###

Developers may add comments providing feedback or to acknowledge their
approval.  Reviewers may end their comments with trailing lines of one
of these forms:

    Acked-by: me
    Reported-by: @someone
    Reviewed-by: Some One <someone@somewhere.org>
    Signed-off-by: ...
    Tested-by: ...

These trailers will be extracted during [merging](#merge-a-topic) and
included as trailing lines of the generated merge commit message.
References to `me` and `@username` will automatically be transformed
into a real name and email address according to the user's GitLab
account profile.

### Robot Reviews ###

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 pushed to your fork again.
A re-check may be explicitly requested by adding a comment with the
trailing line:

    Do: check

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

Ben Boeckel's avatar
Ben Boeckel committed
256
257
258
### Testing ###

ParaView has a [buildbot](http://buildbot.net) instance watching for merge requests
Ben Boeckel's avatar
Ben Boeckel committed
259
to test.  A developer must issue a command to buildbot to enable builds:
Ben Boeckel's avatar
Ben Boeckel committed
260
261
262
263
264
265

    @buildbot test

The buildbot user (@buildbot) will respond with a comment linking to the CDash
results when it schedules builds.

266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
Revise a Topic
--------------

If a topic is approved during GitLab review, skip to the
[next step](#merge-a-topic).  Otherwise, revise the topic
and push it back to GitLab for another review as follows:

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

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

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

Merge a Topic
-------------

After a topic has been reviewed and approved in a GitLab Merge Request,
authorized developers may add a comment of the form

    Do: merge

to ask that the change be merged into the upstream repository.

296
297
298
299
300
301
302
Caveats:
* Currently, developers authorized to do a merge request will be limited to those
who have **Master** privileges on the ParaView Gitlab repository. This preserves the
spirit of **Gatekeeper Review** in the previous development workflow. This decision
may be reevaluated in the future and lifted to encourage a more open development
community.

303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
### 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
describing the failure.  In the case of a conflict, fetch the latest
upstream history and rebase on it:

    $ git fetch origin
    $ git rebase origin/master

(If you are fixing a bug in the latest release then substitute
`origin/release` for `origin/master`.)

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

Delete a Topic
--------------

After a topic has been merged upstream the Merge Request will be closed.
Now you may delete your copies of the branch.

1.  In the GitLab Merge Request page a "**Remove Source Branch**"
    button will appear.  Use it to delete the `my-topic` branch
    from your fork in GitLab.

2.  In your work tree checkout and update the `master` branch:

        $ git checkout master
        $ git pull

3.  Delete the local topic branch:

        $ git branch -d my-topic

    The `branch -d` command works only when the topic branch has been
    correctly merged.  Use `-D` instead of `-d` to force the deletion
    of an unmerged topic branch (warning - you could lose commits).
344
345
346
347
348
349
350
351
352
353
354

Contribute VTK Changes
----------------------

If you have any VTK changes, then you are required to get your changes
incorporated into VTK using [VTK's development workflow][]. Once your VTK topic has
been approved and merged into VTK, add your VTK topic head (or the latest VTK
origin/master which includes your VTK topic head) to commit in a
[ParaView topic](#create-a-topic) and follow the process documented earlier.

[VTK's development workflow]: https://gitlab.kitware.com/vtk/vtk/tree/master/Documentation/dev/git