Commit fa95b570 authored by Utkarsh Ayachit's avatar Utkarsh Ayachit Committed by Kitware Robot

Merge topic 'workflow_docs'

9c6a8098 Removing `priority:moonshot`. Using `priority:low` instead.
b9049621 Add workflow docs
Acked-by: Kitware Robot's avatarKitware Robot <kwrobot@kitware.com>
Merge-request: !959
parents d1d7693c 9c6a8098
Pipeline #23471 running with stage
in 486 minutes and 34 seconds
......@@ -6,6 +6,90 @@ Please check our [developer instructions][] for a more detailed guide to
developing and contributing to the project, and our [ParaView Git README][]
for additional information.
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`,
`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 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:
1. Register [GitLab Access] to create an account and select a user name.
2. [Fork ParaView][] into your user's namespace on GitLab.
......@@ -38,7 +122,8 @@ for additional information.
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.
needed before looking at the code. Appropriately refer to the issue
number, if applicable.
For more information see: [Create a Topic][]
......@@ -54,9 +139,17 @@ for additional information.
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.
ParaView uses GitLab for code review and Buildbot to test proposed
patches before they are merged.
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
......@@ -73,7 +166,14 @@ to provide support.
[Create a Topic]: Documentation/dev/git/develop.md#create-a-topic
[Share a Topic]: Documentation/dev/git/develop.md#share-a-topic
[Create a Merge Request]: Documentation/dev/git/develop.md#create-a-merge-request
[Review a Merge Request]: Documentation/dev/git/develop.md#review-a-merge-request
[review]: Documentation/dev/git/develop.md#review-a-merge-request
[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
[Wiki]: http://www.paraview.org/Wiki/ParaView
[Mailing Lists]: http://www.paraview.org/mailing-lists/
[Gitlab Markdown]: https://gitlab.kitware.com/help/markdown/markdown
[new issue]: https://gitlab.kitware.com/paraview/paraview/issues/new
[Labels Glossary]: Documentation/dev/git/labels.md
......@@ -32,3 +32,8 @@ The upstream ParaView repository has the following branches:
* `nightly-master`: Follows `master`, updated at `01:00 UTC`
* `hooks`: Local commit hooks
([placed](http://public.kitware.com/Wiki/Git/Hooks#Local) in `.git/hooks`)
Labels
------
See [Labels](labels.md) for information on labels for Issues and Merge Requests.
......@@ -88,12 +88,19 @@ 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.
A reader should have a general idea of the feature or fix to be developed given
just the branch name. Additionally, it is preferred to have an issue associated with
every topic. The issue can document the bug or feature to be developed. In such
cases, being your topic name with the issue number.
1. To start a new topic branch:
$ git fetch origin
If there is an issue associated with the topic, assign the issue to yourself
using the "**Assignee**" field, and add the
`workflow:active-development` label to it.
2. For new development, start the topic from `origin/master`:
$ git checkout -b my-topic origin/master
......@@ -235,6 +242,15 @@ 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.
When a merge request is ready for review, developers can use the
`triage:ready-for-review` to indicate the same to the reviewers. If reviewers
deems that it needs more work, they can add the `triage:needswork` label.
This can be repeated as many times as needed adding/removing labels as
appropriate.
If a merge request is waiting on dashboards, use the `triage:pending-dashboards`
label.
[GitLab Flavored Markdown]: https://gitlab.kitware.com/help/markdown/markdown
[Special GitLab References]: https://gitlab.kitware.com/help/markdown/markdown#special-gitlab-references
......@@ -294,14 +310,13 @@ There are a few options for checking out the changes in a work tree:
$ git cherry-pick ..FETCH_HEAD
### 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:
A re-check may be explicitly requested by adding a comment with a single
[*trailing* line](#trailing-lines):
Do: check
......@@ -313,11 +328,49 @@ succeeds.
ParaView has a [buildbot](http://buildbot.net) instance watching for merge requests
to test. A developer must issue a command to buildbot to enable builds:
@buildbot test
Do: test
The buildbot user (@buildbot) will respond with a comment linking to the CDash
results when it schedules builds.
The `Do: test` command accepts the following arguments:
* `--oneshot`
only build the *current* hash of the branch; updates will not be built
using this command
* `--stop`
clear the list of commands for the merge request
* `--superbuild`
build the superbuilds related to the project
* `--clear`
clear previous commands before adding this command
* `--regex-include <arg>` or `-i <arg>`
only build on builders matching `<arg>` (a Python regular expression)
* `--regex-exclude <arg>` or `-e <arg>`
excludes builds on builders matching `<arg>` (a Python regular
expression)
Multiple `Do: test` commands may be given. Upon each update to the branch,
buildbot will reconsider all of the active commands to determine which builders
to schedule.
Builder names always follow this pattern:
project-host-os-libtype-buildtype+feature1+feature2
* project: always `paraview` for paraview
* host: the buildbot host
* os: one of `windows`, `osx`, or `linux`
* libtype: `shared` or `static`
* buildtype: `release` or `debug`
* feature: alphabetical list of features enabled for the build
For a list of all builders, see:
* [paraview-expected](https://buildbot.kitware.com/builders?category=paraview-expected)
* [paraview-superbuild](https://buildbot.kitware.com/builders?category=paraview-superbuild)
* [paraview-experimental](https://buildbot.kitware.com/builders?category=paraview-experimental)
Revise a Topic
--------------
......@@ -360,6 +413,12 @@ loose developer privileges to the repository temporarily (or permanently)!
If the merge succeeds the topic will appear in the upstream repository
`master` branch and the Merge Request will be closed automatically.
Any issues associated with the Merge Request will generally get closed
automatically. If not, the developer merging the changes should close such issues
and add a `workflow:customer-review` tag to the issue(s) addressed by the change.
Reporters and testers can then review the fix. Try to add enough information to
the Issue or the Merge Request to indicate how to test the functionality if not
obvious from the original Issue.
### Merge Failure ###
......
Labels
======
[Labels][] are used to annotate [Issues][] and [Merge Requests][]. They help
organize and provide information about their state in the development
workflow.
Labels are named using the form `[category]:[name]`. Labels in the same category
has the same color.
`area:...`
------------
Labels in this category identify a component of ParaView affected by the issue.
Current list includes `area:catalyst`, `area:doc`, `area:packaging`, `area:third-party`,
and `area:web`.
Reporters and developers can assign these labels to an issue to help organize.
`priority:...`
--------------
An issue gets assigned a **Milestone** to indicate which release a fix for it
is planned for. The `priority:...` label can be used to indicate how critical is
this issue for that milestone.
| label | issues | merge requests | description |
| ----- | -------| -------------- | ----------- |
| `priority:required` | x | | issue is **required** for a milestone (highest priority) |
| `priority:important` | x | | issue is **important** for a milestone but may be okay if missed |
| `priority:nice-to-have` | x | | issue is **nice-to-have**, but not critical or important |
| `priority:low` | x | | low priority issues for a particular milestone |
If an issue targeted for a milestone has no priority label, then it is assumed
the least priority.
`project:...`
---------------
These labels are associated with Issues to identify the project/customer that
wants the issue addressed. Project manager and developers working with their
managers can use these labels to denote the stakeholders for a particular issue.
`triage:...`
--------------
These labels can be assigned to Issues and Merge Requests to help triage as
indicated in the table below:
| label | issues | merge requests | description |
| ----- | -------| -------------- | ----------- |
| `triage:confirmed` | x | | issue has been confirmed by someone other than the reporter |
| `triage:easy` | x | | added by developers to issues that are easy to fix |
| `triage:expired` | x | x | added to issues closed without resolving or merge requests closed without merging due to lack of activity |
| `triage:feature` | x | | issue is a feature request; can be added by developers or reporters |
| `triage:needinfo` | x | x | on an open issue, this label is added to indicate that more information is needed from the reporter; on a closed issue, this label is added to indicate that more information is needed from the developer who closed the issue about how to test or review the issue; on a merge request this label is added to request more information from the developer before the merge request can be reviewed |
| `triage:needswork` | | x | added to merge requests after review if the reviewer deems it needs more work before it can be merged |
| `triage:pending-dashboards` | | x | added to merge requests that are awaiting dashboards before they can be reviewed or merged |
| `triage:ready-for-review` | | x | added to merge requests that are ready for review by a developer |
These labels may be removed if the issue or merge request is no longer in the
state indicated by the label. For example, a merge request gets a `triage:ready-for-review`
label to request another developer to review it. If the reviewer deems it needs
more work, he should add the `triage:needswork` label and remove the `triage:ready-for-review`
label since the latter is no longer applicable.
`workflow:...`
--------------
These labels are added to issues to indicate their state in the development cycle.
Similar to `priority:...`, there can only be at most one workflow label on an issue
at a time.
| label | issues | merge requests | description |
| ----- | -------| -------------- | ----------- |
| `workflow:active-developement` | x | | added to an open issue that is under development |
| `workflow:customer-review` | x | | added to a closed issue that is ready for review by the customer/reporter |
[Labels]: https://gitlab.kitware.com/paraview/paraview/labels
[Issues]: https://gitlab.kitware.com/paraview/paraview/issues
[Merge Requests]: https://gitlab.kitware.com/paraview/paraview/merge_requests
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment