CONTRIBUTING.md 8.16 KB
Newer Older
1
2
3
Contributing to ParaView
========================

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

Utkarsh Ayachit's avatar
Utkarsh Ayachit committed
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
43
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
The ParaView 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 ParaView, you can use the
[issues][] tracker to report a [new issue][].

To report an issue.

1. Register [GitLab Access] to create an account 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.
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/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. `project:...` label to indicate which project this issue is necessary for. An issue
   may have multiple projects associated with it.
2. **Milestone** to indicate which release this issue fix is planned for.
3. `priority:...` label to indicate how critical is this issue for the specific
   milestone, ranging from `priority:required`, `priority:important`,
69
   `priority:nice-to-have`, and `priority:low`. Only one priority label makes
Utkarsh Ayachit's avatar
Utkarsh Ayachit committed
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
   sense at a time.

Notes for developers
--------------------

For every issue, developers can assign:
1. `area:...` labels to indicate which area this issue relates to e.g. `area:web`,
   `area:catalyst`, etc.
2. `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.
3. `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.
4. `workflow:active-development` label should be added to issues under development.


Fixing issues
=============

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

93
94
95
96
1.  Register [GitLab Access] to create an account and select a user name.

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

97
3.  Create a local clone of the main ParaView repository. Optionally configure
98
99
100
101
102
103
104
    Git to [use SSH instead of HTTPS][].
    Then clone:

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

105
    For more information see: [Setup][] and [download instructions][]
106
107
108
109
110
111

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

        $ ./Utilities/SetupForDevelopment.sh
    This will prompt for your GitLab user name and configure a remote
112
    called `gitlab` to refer to it. Choose the defaults for ParaView Data questions.
113
114
115

    For more information see: [Setup][]

116
5.  [Build Paraview][] and run it.
117
118

6.  Edit files and create commits (repeat as needed):
119
120
121
122
123

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

124
125
    Commit messages must be thorough and informative so that
    reviewers will have a good understanding of why the change is
Utkarsh Ayachit's avatar
Utkarsh Ayachit committed
126
127
    needed before looking at the code. Appropriately refer to the issue
    number, if applicable.
128

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

131
7.  Push commits in your topic branch to your fork in GitLab:
132
133
134
135
136

        $ git gitlab-push

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

137
138
139
8.  Run tests with ctest, or use the dashboard

9.  Visit your fork in GitLab, browse to the "**Merge Requests**" link on the
140
141
142
143
144
    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][]

Utkarsh Ayachit's avatar
Utkarsh Ayachit committed
145
146
147
148
149
150
151
152
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.
153

Utkarsh Ayachit's avatar
Utkarsh Ayachit committed
154
155
10. Monitor the related issue for any `triage:needinfo` label additions to provide
    the customer with any details necessary to test the fix.
156
157

Our [Wiki][] is used to document features, flesh out designs and host other
158
159
documentation. We have a [ParaView Discourse][] forum to coordinate development
and to provide support.
160

161
[ParaView Git README]: Documentation/dev/git/README.md
162
163
[developer instructions]: Documentation/dev/git/develop.md
[GitLab Access]: https://gitlab.kitware.com/users/sign_in
164
[Fork ParaView]: https://gitlab.kitware.com/paraview/paraview/-/forks/new
165
166
167
168
[use SSH instead of HTTPS]: Documentation/dev/git/download.md#use-ssh-instead-of-https
[download instructions]: Documentation/dev/git/download.md#clone
[developer setup script]: /Utilities/SetupForDevelopment.sh
[Setup]: Documentation/dev/git/develop.md#Setup
169
[Build Paraview]: Documentation/dev/build.md
Guillermo Vilanova's avatar
Guillermo Vilanova committed
170
[Create a Topic][]: Documentation/dev/git/develop.md#create-a-topic
171
172
[Share a Topic]: Documentation/dev/git/develop.md#share-a-topic
[Create a Merge Request]: Documentation/dev/git/develop.md#create-a-merge-request
Utkarsh Ayachit's avatar
Utkarsh Ayachit committed
173
174
[Review a Merge Request]: Documentation/dev/git/develop.md#review-a-merge-request
[review]: Documentation/dev/git/develop.md#review-a-merge-request
175
176
177
178
[Issues]: https://gitlab.kitware.com/paraview/paraview/-/issues
[Merge Requests]: https://gitlab.kitware.com/paraview/paraview/-/merge_requests
[Labels]: https://gitlab.kitware.com/paraview/paraview/-/labels
[Milestones]: https://gitlab.kitware.com/paraview/paraview/-/milestones
179
[Wiki]: http://www.paraview.org/Wiki/ParaView
180
[ParaView Discourse]: https://discourse.paraview.org/
Utkarsh Ayachit's avatar
Utkarsh Ayachit committed
181
[Gitlab Markdown]: https://gitlab.kitware.com/help/markdown/markdown
182
[new issue]: https://gitlab.kitware.com/paraview/paraview/-/issues/new
Utkarsh Ayachit's avatar
Utkarsh Ayachit committed
183
[Labels Glossary]: Documentation/dev/git/labels.md