Commit cb77ffae authored by Ben Boeckel's avatar Ben Boeckel Committed by Kitware Robot

Merge topic 'developer-setup-gitlab'

8b49512b README.html: Remove out-dated document
ef92e521 README.md: Add document introducing VTK and linking to resources
8c49fc08 CONTRIBUTING: Update for GitLab workflow
9f088f0c Documentation: Add VTK Git instructions
328cb759 Tell Git how to check Markdown (.md) source files
b1a0f22e Switch developer setup to use the GitLab workflow
ac802c7c Disable gerrit-push and stage aliases
98ecd485 Drop mention of Gerrit from instructions in third-party README files
...
Acked-by: Kitware Robot's avatarKitware Robot <kwrobot@kitware.com>
Acked-by: Ben Boeckel's avatarBen Boeckel <ben.boeckel@kitware.com>
Merge-request: !2
parents 63dc21a2 8b49512b
......@@ -14,4 +14,6 @@ pre-commit crlf=input
*.txt whitespace=tab-in-indent
*.cmake whitespace=tab-in-indent
*.md whitespace=tab-in-indent conflict-marker-size=30
/ThirdParty/sqlite/vtksqlite/vtk_sqlite3.c hooks.MaxObjectKiB=4096
......@@ -60,7 +60,7 @@ list(APPEND ExternalData_URL_TEMPLATES
# Data published by MIDAS
"http://midas3.kitware.com/midas/api/rest?method=midas.bitstream.download&checksum=%(hash)&algorithm=%(algo)"
# Data published by developers using git-gerrit-push.
# Data published by developers using git-gitlab-push.
"http://www.vtk.org/files/ExternalData/%(algo)/%(hash)"
)
......
Contributing
------------
Contributing to VTK
===================
Our project uses Gerrit for code review, and CDash@Home to test proposed
patches before they are merged. Please check our [development][Development]
guide for details on developing and contributing to the project.
Our project uses GitLab for code review and Buildbot to test proposed
patches before they are merged. Please check our [VTK Git][]
instructions for details on developing and contributing to the project.
Our [wiki][Wiki] is used to document features, flesh out designs and host other
documentation. Our API is [documented using Doxygen][Doxygen] with updated
documentation generated nightly. We have several [mailing lists][MailingLists]
Our [Wiki][] is used to document features, flesh out designs and host other
documentation. Our API is documented using [Doxygen][] with updated
documentation generated nightly. We have several [Mailing Lists][]
to coordinate development and to provide support.
[Development]: https://docs.google.com/a/kitware.com/document/d/1nzinw-dR5JQRNi_gb8qwLL5PnkGMK2FETlQGLr10tZw/view "Development guide"
[Wiki]: http://www.vtk.org/Wiki/VTK "VTK wiki"
[Doxygen]: http://www.vtk.org/doc/nightly/html "API documentation"
[MailingLists]: http://www.vtk.org/VTK/help/mailing.html "Mailing Lists"
[VTK Git]: Documentation/dev/git/README.md
[Wiki]: http://www.vtk.org/Wiki/VTK
[Doxygen]: http://www.vtk.org/doc/nightly/html
[Mailing Lists]: http://www.vtk.org/VTK/help/mailing.html
VTK Git Usage
=============
VTK version tracking and development is hosted by [Git](http://git-scm.com).
Please select a task for further instructions:
Main Tasks
----------
* [Install Git](http://public.kitware.com/Wiki/Git/Download) -
Git 1.6.6 or greater is preferred (required for development)
* [Download VTK](download.md) - Users start here
* [Develop VTK](develop.md) - Contributors start here
Other Tasks
-----------
* [Review Changes](https://gitlab.kitware.com/vtk/vtk/merge_requests) -
VTK GitLab Merge Requests
* [Test VTK](dashboard.md) - CDash client setup
* [Learn Git](http://public.kitware.com/Wiki/Git/Resources) -
Third-party documentation
Branches
--------
The upstream VTK repository has the following branches:
* `master`: Development (default)
* `release`: Maintenance of latest release
* `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`)
* `dashboard`: Dashboard script ([setup](dashboard.md) a CDash client)
VTK Dashboard Scripts
=====================
This page documents how to use the VTK `dashboard` branch in [Git][].
See the [README](README.md) for more information.
[Git]: http://git-scm.com
Using the Dashboard Scripts
---------------------------
The `dashboard` branch contains a dashboard client helper script.
Use these commands to track it:
$ mkdir -p ~/Dashboards/VTKScripts
$ cd ~/Dashboards/VTKScripts
$ git init
$ git remote add -t dashboard origin https://gitlab.kitware.com/vtk/vtk.git
$ git pull origin
The `vtk_common.cmake` script contains setup instructions in its
top comments.
Update the `dashboard` branch to get the latest version of this
script by simply running:
$ git pull
Here is a link to the script as it appears today: [vtk_common.cmake][].
[vtk_common.cmake]: https://gitlab.kitware.com/vtk/vtk/tree/dashboard/vtk_common.cmake
Changing the Dashboard Scripts
------------------------------
If you find bugs in the hooks themselves or would like to add new features,
the can be edited in the usual Git manner:
$ git checkout -b my-topic-branch
Make your edits, test it, and commit the result. Create a patch file with:
$ git format-patch origin/dashboard
And email the results to the developer's mailing list.
This diff is collapsed.
Develop VTK with Git
====================
This page documents how to develop VTK through [Git][].
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.
Here we document procedures used by the VTK development community.
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:
1. Register [GitLab Access].
2. Follow the [download instructions](download.md#clone) to create a
local VTK clone:
$ git clone https://gitlab.kitware.com/vtk/vtk.git VTK
$ cd VTK
3. Run the [developer setup script][] to prepare your VTK work tree and
create Git command aliases used below:
$ ./Utilities/SetupForDevelopment.sh
4. (Optional but highly recommended.)
[Register](https://open.cdash.org/register.php) with the VTK project
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.
[GitLab Access]: https://gitlab.kitware.com/users/sign_in
[developer setup script]: /Utilities/SetupForDevelopment.sh
Workflow
--------
VTK development uses a [branchy workflow][] based on topic branches.
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
$ git pull
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
3. Edit files and create commits (repeat as needed):
$ edit file1 file2 file3
$ git add file1 file2 file3
$ git commit
Caveats:
* To add data follow [these instructions](data.md).
* If your change modifies the `Utilities/KWSys/vtksys` directory please
contribute directly to [KWSys][] instead.
* If your change modifies the `Utilities/MetaIO/vtkmetaio` directory please
contribute directly to [MetaIO][] instead.
[KWSys]: http://public.kitware.com/Wiki/KWSys/Git
[MetaIO]: https://github.com/Kitware/MetaIO
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 GitLab][] repository page and using the "Fork" button in the upper right.
[VTK GitLab]: https://gitlab.kitware.com/vtk/vtk
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.
* If the topic adds data see [this note](data.md#push).
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:
https://gitlab.kitware.com/<username>/vtk/merge_requests/new
Follow these steps:
1. In the "**Source branch**" box select the `<username>/vtk` repository
and the `my-topic` branch.
2. In the "**Target branch**" box select the `vtk/vtk` repository and
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.
3. Use the "**Compare branches**" button to proceed to the next page.
4. Fill out the form and use the "**Submit merge request**" button to
create the merge request and visit its page.
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. Use `@username` syntax to draw attention of
specific 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`, such as
```message
This topic adds a really cool feature.
```
to specify text to be included in the generated merge commit message
when the topic is [merged](#merge-a-topic). Do not use `@username`
syntax in this block as it will not be interpreted.
Review a Merge Request
----------------------
Add comments mentioning specific developers using `@username` syntax to
draw their attention and have the topic reviewed.
### 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.
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.
### 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).
Download VTK with Git
=====================
This page documents how to download VTK source code through [Git][].
See the [README](README.md) for more information.
[Git]: http://git-scm.com
Clone
-----
Clone VTK using the commands:
$ git clone https://gitlab.kitware.com/vtk/vtk.git VTK
$ cd VTK
Update
------
Users that have made no local changes and simply want to update a
clone with the latest changes may run:
$ git pull
Avoid making local changes unless you have read our [developer instructions][].
[developer instructions]: develop.md
Release
-------
After cloning your local repository will be configured to follow the upstream
`master` branch by default. One may create a local branch to track the
upstream `release` branch instead, which should guarantee only bug fixes to
the functionality available in the latest release:
$ git checkout --track -b release origin/release
This local branch will always follow the latest release.
Use the [above instructions](#update) to update it.
Alternatively one may checkout a specific release tag:
$ git checkout v6.2.0
Release tags never move. Repeat the command with a different tag to get a
different release. One may list available tags:
$ git tag
and then checkout any tag listed.
......@@ -40,8 +40,7 @@ appropriate date and version number:
git commit --amend
Edit the commit message to describe the procedure used to obtain the
content. Be sure to add a gerrit change-id line to the bottom of the
message. Then push the changes back up to the main local repository:
content. Then push the changes back up to the main local repository:
git push .. HEAD:xdmf2vtk-upstream
cd ..
......
This diff is collapsed.
![VTK - The Visualization Toolkit](vtkBanner.gif)
Introduction
============
VTK is an open-source software system for image processing, 3D
graphics, volume rendering and visualization. VTK includes many
advanced algorithms (e.g., surface reconstruction, implicit modelling,
decimation) and rendering techniques (e.g., hardware-accelerated
volume rendering, LOD control).
VTK is used by academicians for teaching and research; by government
research institutions such as Los Alamos National Lab in the US or
CINECA in Italy; and by many commercial firms who use VTK to build or
extend products.
The origin of VTK is with the textbook "The Visualization Toolkit, an
Object-Oriented Approach to 3D Graphics" originally published by
Prentice Hall and now published by Kitware, Inc. (Third Edition ISBN
1-930934-07-6). VTK has grown (since its initial release in 1994) to a
world-wide user base in the commercial, academic, and research
communities.
Learning Resources
==================
* General information is available at the [VTK Homepage][].
* Community discussion takes place on the [VTK Mailing Lists][].
* Commercial [support][Kitware Support] and [training][Kitware Training]
are available from [Kitware][].
* Doxygen-generated nightly reference documentation is
available [online][Doxygen].
[VTK Homepage]: http://www.vtk.org
[Doxygen]: http://www.vtk.org/doc/nightly/html
[VTK Mailing Lists]: http://www.vtk.org/VTK/help/mailing.html
[Kitware]: http://www.kitware.com/
[Kitware Support]: http://www.kitware.com/products/support.html
[Kitware Training]: http://www.kitware.com/products/protraining.php
Reporting Bugs
==============
If you have found a bug:
1. If you have a patch, please read the [CONTRIBUTING.md][] document.
2. Otherwise, please join the one of the [VTK Mailing Lists][] and ask
about the expected and observed behaviors to determine if it is
really a bug.
3. Finally, if the issue is not resolved by the above steps, open
an entry in the [VTK Issue Tracker][].
[VTK Issue Tracker]: http://www.vtk.org/Bug
License
=======
VTK is distributed under the OSI-approved BSD 3-clause License.
See [Copyright.txt][] for details.
[Copyright.txt]: Copyright.txt
Contributing
============
See [CONTRIBUTING.md][] for instructions to contribute.
[CONTRIBUTING.md]: CONTRIBUTING.md
......@@ -47,9 +47,6 @@ content. Then push the changes back up to the main repository:
cd ..
rm -rf hdf5-tmp
Make sure your commit in 'hdf5-upstream' has a 'Change-Id: ...', otherwise
you won't be able to commit your change into gerrit.
Create a topic in the main repository on which to perform the update:
git checkout -b update-hdf5 master
......
......@@ -40,8 +40,7 @@ appropriate date and version number:
git commit --amend
Edit the commit message to describe the procedure used to obtain the
content. Be sure to add a Gerrit Change-Id line to the bottom of the
message. Then push the changes back up to the main local repository:
content. Then push the changes back up to the main local repository:
git push .. HEAD:netcdf-upstream
cd ..
......
......@@ -40,8 +40,7 @@ appropriate date and version number:
git commit --amend
Edit the commit message to describe the procedure used to obtain the
content. Be sure to add a Gerrit Change-Id line to the bottom of the
message. Then push the changes back up to the main local repository:
content. Then push the changes back up to the main local repository:
git push .. HEAD:verdict-upstream
cd ..
......
......@@ -40,8 +40,7 @@ appropriate date and version number:
git commit --amend
Edit the commit message to describe the procedure used to obtain the
content. Be sure to add a gerrit change-id line to the bottom of the
message. Then push the changes back up to the main local repository:
content. Then push the changes back up to the main local repository:
git push .. HEAD:xdmf2-upstream
cd ..
......
......@@ -3,5 +3,7 @@
# Exclude from source archives files specific to Git work tree.
* export-ignore
config* eol=lf whitespace=indent-with-non-tab
git-* eol=lf whitespace=indent-with-non-tab
tips eol=lf whitespace=indent-with-non-tab
setup-* eol=lf whitespace=indent-with-non-tab
[hooks]
url = http://vtk.org/VTK.git
[ssh]
host = vtk.org
key = id_git_vtk
request-url = https://www.kitware.com/Admin/SendPassword.cgi
[gerrit]
project = VTK
site = http://review.source.kitware.com
pushurl = $username@review.source.kitware.com:VTK
url = https://gitlab.kitware.com/vtk/vtk.git
[upstream]
url = https://gitlab.kitware.com/vtk/vtk.git
[gitlab]
host = gitlab.kitware.com
group-path = vtk
group-name = VTK
project-path = vtk
project-name = VTK
......@@ -20,3 +20,13 @@
site = http://review.source.kitware.com
# pushurl placeholder "$username" is literal
pushurl = $username@review.source.kitware.com:Project
[upstream]
url = git://public.kitware.com/Project.git
[gitlab]
host = gitlab.kitware.com
group-path = group
group-name = Group
project-path = project
project-name = Project
#!/usr/bin/env bash
#=============================================================================
# Copyright 2010-2015 Kitware, Inc.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#=============================================================================
USAGE="[<remote>] [--no-topic] [--dry-run] [--]"
OPTIONS_SPEC=
SUBDIRECTORY_OK=Yes
. "$(git --exec-path)/git-sh-setup"
#-----------------------------------------------------------------------------
remote=''
refspecs=''
no_topic=''
dry_run=''
# Parse the command line options.
while test $# != 0; do
case "$1" in
--no-topic) no_topic=1 ;;
--dry-run) dry_run=--dry-run ;;
--) shift; break ;;
-*) usage ;;
*) test -z "$remote" || usage ; remote="$1" ;;
esac
shift
done
test $# = 0 || usage
# Default remote.
test -n "$remote" || remote="gerrit"