https://public.kitware.com/Wiki/api.php?action=feedcontributions&user=Xiaoxiao&feedformat=atomKitwarePublic - User contributions [en]2024-03-29T06:50:52ZUser contributionsMediaWiki 1.38.6https://public.kitware.com/Wiki/index.php?title=TubeTK/Build_Instructions&diff=55041TubeTK/Build Instructions2014-01-07T18:20:13Z<p>Xiaoxiao: </p>
<hr />
<div>= Overview =<br />
<br />
TubeTK has been tested on Windows, OS X, and Linux.<br />
<br />
* Process<br />
** Install dependencies<br />
** Download source<br />
** Configure using CMake<br />
** Build<br />
<br />
= Dependencies =<br />
<br />
=== Minimum Requirements ===<br />
* [http://cmake.org CMake]<br />
* [http://git-scm.com Git]<br />
* [http://subversion.apache.org Subversion]<br />
<br />
The following third-party libraries will be downloaded and built automatically (via the cmake superbuild mechanism):<br />
* [http://jsoncpp.sourceforge.net JsonCpp]<br />
* [https://github.com/Slicer/SlicerExecutionModel Slicer Execution Model]<br />
* [http://itk.org/ Insight Segmentation and Registration Toolkit] (ITK)<br />
* [https://github.com/Slicer/VTK 3D Slicer fork] of the [http://vtk.org Visualization Toolkit] (VTK)<br />
<br />
See the [https://github.com/TubeTK/TubeTK/wiki/Dependencies Dependencies] page on GitHub for minimum versions and a complete list.<br />
<br />
=== Using Binary Packages ===<br />
* Fedora:<br />
sudo yum install cmake git gcc-c++ jsoncpp-devel make mesa-libGL-devel subversion<br />
* Red Hat Enterprise Linux:<br />
sudo yum install cmake28 devtoolset-1.1-gcc-c++ git make mesa-libGL-devel subversion<br />
* Ubuntu:<br />
sudo apt-get install cmake git g++ libgl1-mesa-dev libjsoncpp-dev make subversion<br />
<br />
Note: For Red Hat Enterprise Linux, first enable [https://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F Extra Packages for Enterprise Linux (EPEL)].<br />
<br />
= Download, Configure, and Build =<br />
<br />
You have two options:<br />
<br />
== 1. Download, configure, and build manually ==<br />
<br />
=== 1a. Clone the Git repository ===<br />
==== Windows, Linux, and OS X: Command-line Option ====<br />
cd <where you want the top-level source directory to be><br />
git clone https://github.com/TubeTK/TubeTK TubeTK<br />
<br />
==== Windows, Linux, and OS X: Using the GitHub gui ====<br />
Follow the directions for cloning a repo to your machine<br />
* On the right side of the page, you'll find a button to "Clone in Desktop". Click this.<br />
* The GitHub app will open.<br />
* Log in if it asks you to, and specify a convenient location on your computer for the project folder.<br />
<br />
=== 1b. Configure ===<br />
<br />
==== Windows ====<br />
mkdir %HOMEPATH%/TubeTK-Release<br />
cd %HOMEPATH%/TubeTK-Release<br />
cmake -DCMAKE_BUILD_TYPE=Release ../TubeTK<br />
<br />
==== Linux and OS X ====<br />
* Fedora, Ubuntu, and OS X:<br />
mkdir $HOME/TubeTK-Release<br />
cd $HOME/TubeTK-Release<br />
cmake -G"Unix Makefiles" -DCMAKE_BUILD_TYPE=Release ../TubeTK<br />
* Red Hat Enterprise Linux:<br />
mkdir $HOME/TubeTK-Release<br />
cd $HOME/TubeTK-Release<br />
cmake28 -G"Unix Makefiles" -DCMAKE_BUILD_TYPE=Release ../TubeTK<br />
<br />
=== 1c. Build ===<br />
<br />
==== Windows ====<br />
Microsoft Visual Studio<br />
* Load the TubeTK solution file<br />
** Select File -> Open -> Project/Solution -> open TubeTK-Release/TubeTK.sln<br />
* Perform the initial build using your compiler at the top-level of TubeTK-Release. This will update and build the libraries that TubeTK depends on (ex. VTK, ITK), and then build TubeTK.<br />
** Right click on the "ALL_BUILD" project and select "Build".<br />
* Subsequent builds should be initiated in the subdir TubeTK-Release/TubeTK-build to save time. This will build TubeTK only. You may have to periodically build from the top-level of TubeTK-Release to get updates to the libraries that TubeTK depends on.<br />
** Right click on the "TubeTK" project and select "Build".<br />
<br />
==== Linux and OS X ====<br />
* Perform the initial build using your compiler at the top-level of TubeTK-Release. This will update and build the libraries that TubeTK depends on (ex. VTK, ITK), and then build TubeTK.<br />
cd $HOME/TubeTK-Release<br />
make<br />
* Subsequent builds should be initiated in the subdir TubeTK-Release/TubeTK-build to save time. This will build TubeTK only. You may have to periodically build from the top-level of TubeTK-Release to get updates to the libraries that TubeTK depends on.<br />
cd $HOME/TubeTK-Release/TubeTK-build<br />
make<br />
== 2. Dashboard Testing==<br />
*Details on setting up a nightly dashboard : [[TubeTK/Dashboard Scripts]].<br />
<br />
<br />
== 3. Have CTest do all of the work ==<br />
<br><br />
<br><br />
<em> THIS METHOD IS NOT WORKING AT THIS TIME - WE NEED TO UPDATE THE BUILD FILES MENTIONED BELOW. </em><br />
<br><br />
<br><br />
<em> SORRY FOR THE INCONVENIENCE - PLEASE USE THE MANUAL BUILD METHOD DESCRIBED ABOVE</em><br />
<br><br />
<br><br />
<br />
This is the recommended approach for people who will be using and developing in TubeTK. It not only builds and tests TubeTK with minimal effort, but it also submits your build as an "experimental" on the TubeTK dashboard - this allows us to more easily help you debug errors during the build process:<br />
<br />
* Download a ctest configuration file for TubeTK<br />
:Linux: [https://github.com/TubeTK/TubeTK/blob/master/CMake/TubeTK_InitialBuild_Linux.cmake TubeTK_InitialBuild_Linux.cmake]<br />
:OS X:[https://github.com/TubeTK/TubeTK/blob/master/CMake/TubeTK_InitialBuild_Mac.cmake TubeTK_InitialBuild_Mac.cmake]<br />
:Windows: [https://github.com/TubeTK/TubeTK/blob/master/CMake/TubeTK_InitialBuild_Windows.cmake TubeTK_InitialBuild_Windows.cmake]<br />
* Edit it to match your environment<br />
** Only the variables in the first portion of the file should be edited. They are clearly marked and self explanatory. Additional details are at [[TubeTK/Dashboard Scripts]].<br />
* Run ctest and submit an experimental dashboard<br />
:Fedora and Ubuntu:<br />
:<code>ctest -S TubeTK_InitialBuild_Linux.cmake</code><br />
:Red Hat Enterprise Linux:<br />
:<code>ctest28 -S TubeTK_InitialBuild_Linux.cmake</code><br />
:OS X:<br />
:<code>ctest -S TubeTK_InitialBuild_Mac.cmake</code><br />
:Windows:<br />
:<code>ctest -S TubeTK_InitialBuild_Windows.cmake</code><br />
:This will download the source code, configure it, build it, test it, and then submit the results to the [http://open.cdash.org/index.php?project=TubeTK TubeTK Dashboard].<br />
<br />
= Advanced =<br />
<br />
== Using KWStyle ==<br />
For introductory information, see: [http://public.kitware.com/KWStyle/ http://public.kitware.com/KWStyle/].<br />
git clone http://public.kitware.com/KWStyle.git $HOME/KWStyle<br />
mkdir $HOME/KWStyle-Release<br />
cd $HOME/KWStyle-Release<br />
cmake -DCMAKE_BUILD_TYPE=Release ../KWStyle<br />
make<br />
sudo make install<br />
<br />
cd $HOME/TubeTK-Release<br />
cmake -DTubeTK_USE_KWSTYLE=ON -DKWSTYLE_EXECUTABLE=/usr/local/bin/KWStyle .<br />
make<br />
make StyleCheck<br />
<br />
== Using a pre-existing ITK, JsonCpp, or VTK installation ==<br />
You can also configure CMake variables to use an existing JsonCpp installation instead of an embedded version.<br />
cd $HOME/TubeTK-Release<br />
cmake -DUSE_SYSTEM_JSONCPP .<br />
<br />
You can also configure CMake variables to use an existing ITK or VTK installation instead of an embedded versions. This is not recommended, because of inter-dependencies that require specific version of these libraries, and built using specific options, to be used.<br />
* USE_SYSTEM_ITK: OFF<br />
** If "ON", then you can tell TubeTK to use an ITK build that is already present on your system (using the CMake variable ITK_DIR).<br />
* USE_SYSTEM_VTK: OFF<br />
** If "ON", then you can tell TubeTK to use a VTK build that is already present on your system (using the CMake variable VTK_DIR). See the warning below.<br />
<br />
* Dependency on VTK version and build options<br />
** Note that TubeTK relies on VTK from 3D Slicer (https://github.com/Slicer/VTK)<br />
** The 3D Slicer fork of VTK contains enhancements that have not yet made it into the VTK repository itself.<br />
<br />
[[Category:TubeTK|Build Instructions]]</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=TubeTK/Build_Instructions&diff=55040TubeTK/Build Instructions2014-01-07T18:16:42Z<p>Xiaoxiao: /* 2. Have CTest do all of the remaining work */</p>
<hr />
<div>= Overview =<br />
<br />
TubeTK has been tested on Windows, OS X, and Linux.<br />
<br />
* Process<br />
** Install dependencies<br />
** Download source<br />
** Configure using CMake<br />
** Build<br />
<br />
= Dependencies =<br />
<br />
=== Minimum Requirements ===<br />
* [http://cmake.org CMake]<br />
* [http://git-scm.com Git]<br />
* [http://subversion.apache.org Subversion]<br />
<br />
The following third-party libraries will be downloaded and built automatically (via the cmake superbuild mechanism):<br />
* [http://jsoncpp.sourceforge.net JsonCpp]<br />
* [https://github.com/Slicer/SlicerExecutionModel Slicer Execution Model]<br />
* [http://itk.org/ Insight Segmentation and Registration Toolkit] (ITK)<br />
* [https://github.com/Slicer/VTK 3D Slicer fork] of the [http://vtk.org Visualization Toolkit] (VTK)<br />
<br />
See the [https://github.com/TubeTK/TubeTK/wiki/Dependencies Dependencies] page on GitHub for minimum versions and a complete list.<br />
<br />
=== Using Binary Packages ===<br />
* Fedora:<br />
sudo yum install cmake git gcc-c++ jsoncpp-devel make mesa-libGL-devel subversion<br />
* Red Hat Enterprise Linux:<br />
sudo yum install cmake28 devtoolset-1.1-gcc-c++ git make mesa-libGL-devel subversion<br />
* Ubuntu:<br />
sudo apt-get install cmake git g++ libgl1-mesa-dev libjsoncpp-dev make subversion<br />
<br />
Note: For Red Hat Enterprise Linux, first enable [https://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F Extra Packages for Enterprise Linux (EPEL)].<br />
<br />
= Download, Configure, and Build =<br />
<br />
You have two options:<br />
<br />
== 1. Download, configure, and build manually ==<br />
<br />
=== 1a. Clone the Git repository ===<br />
==== Windows, Linux, and OS X: Command-line Option ====<br />
cd <where you want the top-level source directory to be><br />
git clone https://github.com/TubeTK/TubeTK TubeTK<br />
<br />
==== Windows, Linux, and OS X: Using the GitHub gui ====<br />
Follow the directions for cloning a repo to your machine<br />
* On the right side of the page, you'll find a button to "Clone in Desktop". Click this.<br />
* The GitHub app will open.<br />
* Log in if it asks you to, and specify a convenient location on your computer for the project folder.<br />
<br />
=== 1b. Configure ===<br />
<br />
==== Windows ====<br />
mkdir %HOMEPATH%/TubeTK-Release<br />
cd %HOMEPATH%/TubeTK-Release<br />
cmake -DCMAKE_BUILD_TYPE=Release ../TubeTK<br />
<br />
==== Linux and OS X ====<br />
* Fedora, Ubuntu, and OS X:<br />
mkdir $HOME/TubeTK-Release<br />
cd $HOME/TubeTK-Release<br />
cmake -G"Unix Makefiles" -DCMAKE_BUILD_TYPE=Release ../TubeTK<br />
* Red Hat Enterprise Linux:<br />
mkdir $HOME/TubeTK-Release<br />
cd $HOME/TubeTK-Release<br />
cmake28 -G"Unix Makefiles" -DCMAKE_BUILD_TYPE=Release ../TubeTK<br />
<br />
=== 1c. Build ===<br />
<br />
==== Windows ====<br />
Microsoft Visual Studio<br />
* Load the TubeTK solution file<br />
** Select File -> Open -> Project/Solution -> open TubeTK-Release/TubeTK.sln<br />
* Perform the initial build using your compiler at the top-level of TubeTK-Release. This will update and build the libraries that TubeTK depends on (ex. VTK, ITK), and then build TubeTK.<br />
** Right click on the "ALL_BUILD" project and select "Build".<br />
* Subsequent builds should be initiated in the subdir TubeTK-Release/TubeTK-build to save time. This will build TubeTK only. You may have to periodically build from the top-level of TubeTK-Release to get updates to the libraries that TubeTK depends on.<br />
** Right click on the "TubeTK" project and select "Build".<br />
<br />
==== Linux and OS X ====<br />
* Perform the initial build using your compiler at the top-level of TubeTK-Release. This will update and build the libraries that TubeTK depends on (ex. VTK, ITK), and then build TubeTK.<br />
cd $HOME/TubeTK-Release<br />
make<br />
* Subsequent builds should be initiated in the subdir TubeTK-Release/TubeTK-build to save time. This will build TubeTK only. You may have to periodically build from the top-level of TubeTK-Release to get updates to the libraries that TubeTK depends on.<br />
cd $HOME/TubeTK-Release/TubeTK-build<br />
make<br />
<br />
== 2. Have CTest do all of the work ==<br />
<br><br />
<br><br />
<em> THIS METHOD IS NOT WORKING AT THIS TIME - WE NEED TO UPDATE THE BUILD FILES MENTIONED BELOW. </em><br />
<br><br />
<br><br />
<em> SORRY FOR THE INCONVENIENCE - PLEASE USE THE MANUAL BUILD METHOD DESCRIBED ABOVE</em><br />
<br><br />
<br><br />
<br />
This is the recommended approach for people who will be using and developing in TubeTK. It not only builds and tests TubeTK with minimal effort, but it also submits your build as an "experimental" on the TubeTK dashboard - this allows us to more easily help you debug errors during the build process:<br />
<br />
* Download a ctest configuration file for TubeTK<br />
:Linux: [https://github.com/TubeTK/TubeTK/blob/master/CMake/TubeTK_InitialBuild_Linux.cmake TubeTK_InitialBuild_Linux.cmake]<br />
:OS X:[https://github.com/TubeTK/TubeTK/blob/master/CMake/TubeTK_InitialBuild_Mac.cmake TubeTK_InitialBuild_Mac.cmake]<br />
:Windows: [https://github.com/TubeTK/TubeTK/blob/master/CMake/TubeTK_InitialBuild_Windows.cmake TubeTK_InitialBuild_Windows.cmake]<br />
* Edit it to match your environment<br />
** Only the variables in the first portion of the file should be edited. They are clearly marked and self explanatory. Additional details are at [[TubeTK/Dashboard Scripts]].<br />
* Run ctest and submit an experimental dashboard<br />
:Fedora and Ubuntu:<br />
:<code>ctest -S TubeTK_InitialBuild_Linux.cmake</code><br />
:Red Hat Enterprise Linux:<br />
:<code>ctest28 -S TubeTK_InitialBuild_Linux.cmake</code><br />
:OS X:<br />
:<code>ctest -S TubeTK_InitialBuild_Mac.cmake</code><br />
:Windows:<br />
:<code>ctest -S TubeTK_InitialBuild_Windows.cmake</code><br />
:This will download the source code, configure it, build it, test it, and then submit the results to the [http://open.cdash.org/index.php?project=TubeTK TubeTK Dashboard].<br />
<br />
= Advanced =<br />
<br />
== Using KWStyle ==<br />
For introductory information, see: [http://public.kitware.com/KWStyle/ http://public.kitware.com/KWStyle/].<br />
git clone http://public.kitware.com/KWStyle.git $HOME/KWStyle<br />
mkdir $HOME/KWStyle-Release<br />
cd $HOME/KWStyle-Release<br />
cmake -DCMAKE_BUILD_TYPE=Release ../KWStyle<br />
make<br />
sudo make install<br />
<br />
cd $HOME/TubeTK-Release<br />
cmake -DTubeTK_USE_KWSTYLE=ON -DKWSTYLE_EXECUTABLE=/usr/local/bin/KWStyle .<br />
make<br />
make StyleCheck<br />
<br />
== Using a pre-existing ITK, JsonCpp, or VTK installation ==<br />
You can also configure CMake variables to use an existing JsonCpp installation instead of an embedded version.<br />
cd $HOME/TubeTK-Release<br />
cmake -DUSE_SYSTEM_JSONCPP .<br />
<br />
You can also configure CMake variables to use an existing ITK or VTK installation instead of an embedded versions. This is not recommended, because of inter-dependencies that require specific version of these libraries, and built using specific options, to be used.<br />
* USE_SYSTEM_ITK: OFF<br />
** If "ON", then you can tell TubeTK to use an ITK build that is already present on your system (using the CMake variable ITK_DIR).<br />
* USE_SYSTEM_VTK: OFF<br />
** If "ON", then you can tell TubeTK to use a VTK build that is already present on your system (using the CMake variable VTK_DIR). See the warning below.<br />
<br />
* Dependency on VTK version and build options<br />
** Note that TubeTK relies on VTK from 3D Slicer (https://github.com/Slicer/VTK)<br />
** The 3D Slicer fork of VTK contains enhancements that have not yet made it into the VTK repository itself.<br />
<br />
[[Category:TubeTK|Build Instructions]]</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=TubeTK/Build_Instructions&diff=55030TubeTK/Build Instructions2014-01-06T22:06:18Z<p>Xiaoxiao: </p>
<hr />
<div>= Overview =<br />
<br />
TubeTK has been tested on Windows, OS X, and Linux.<br />
<br />
* Process<br />
** Install dependencies<br />
** Download source<br />
** Configure using CMake<br />
** Build<br />
<br />
= Dependencies =<br />
<br />
=== Minimum Requirements ===<br />
* [http://cmake.org CMake]<br />
* [http://git-scm.com Git]<br />
* [http://subversion.apache.org Subversion]<br />
<br />
The following third-party libraries will be downloaded and built automatically (via the cmake superbuild mechanism):<br />
* [http://jsoncpp.sourceforge.net JsonCpp]<br />
* [https://github.com/Slicer/SlicerExecutionModel Slicer Execution Model]<br />
* [http://itk.org/ Insight Segmentation and Registration Toolkit] (ITK)<br />
* [https://github.com/Slicer/VTK 3D Slicer fork] of the [http://vtk.org Visualization Toolkit] (VTK)<br />
<br />
See the [https://github.com/TubeTK/TubeTK/wiki/Dependencies Dependencies] page on GitHub for minimum versions and a complete list.<br />
<br />
=== Using Binary Packages ===<br />
* Fedora:<br />
sudo yum install cmake git gcc-c++ jsoncpp-devel make mesa-libGL-devel subversion<br />
* Red Hat Enterprise Linux:<br />
sudo yum install cmake28 devtoolset-1.1-gcc-c++ git make mesa-libGL-devel subversion<br />
* Ubuntu:<br />
sudo apt-get install cmake git g++ libgl1-mesa-dev libjsoncpp-dev make subversion<br />
<br />
Note: For Red Hat Enterprise Linux, first enable [https://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F Extra Packages for Enterprise Linux (EPEL)].<br />
<br />
= Download, Configure, and Build =<br />
<br />
You have two options:<br />
<br />
== 1. Download, configure, and build manually ==<br />
<br />
=== 1a. Clone the Git repository ===<br />
==== Windows, Linux, and OS X: Command-line Option ====<br />
cd <where you want the top-level source directory to be><br />
git clone https://github.com/TubeTK/TubeTK TubeTK<br />
<br />
==== Windows, Linux, and OS X: Using the GitHub gui ====<br />
Follow the directions for cloning a repo to your machine<br />
* On the right side of the page, you'll find a button to "Clone in Desktop". Click this.<br />
* The GitHub app will open.<br />
* Log in if it asks you to, and specify a convenient location on your computer for the project folder.<br />
<br />
=== 1b. Configure ===<br />
<br />
==== Windows ====<br />
mkdir %HOMEPATH%/TubeTK-Release<br />
cd %HOMEPATH%/TubeTK-Release<br />
cmake -DCMAKE_BUILD_TYPE=Release ../TubeTK<br />
<br />
==== Linux and OS X ====<br />
* Fedora, Ubuntu, and OS X:<br />
mkdir $HOME/TubeTK-Release<br />
cd $HOME/TubeTK-Release<br />
cmake -G"Unix Makefiles" -DCMAKE_BUILD_TYPE=Release ../TubeTK<br />
* Red Hat Enterprise Linux:<br />
mkdir $HOME/TubeTK-Release<br />
cd $HOME/TubeTK-Release<br />
cmake28 -G"Unix Makefiles" -DCMAKE_BUILD_TYPE=Release ../TubeTK<br />
<br />
=== 1c. Build ===<br />
<br />
==== Windows ====<br />
Microsoft Visual Studio<br />
* Load the TubeTK solution file<br />
** Select File -> Open -> Project/Solution -> open TubeTK-Release/TubeTK.sln<br />
* Perform the initial build using your compiler at the top-level of TubeTK-Release. This will update and build the libraries that TubeTK depends on (ex. VTK, ITK), and then build TubeTK.<br />
** Right click on the "ALL_BUILD" project and select "Build".<br />
* Subsequent builds should be initiated in the subdir TubeTK-Release/TubeTK-build to save time. This will build TubeTK only. You may have to periodically build from the top-level of TubeTK-Release to get updates to the libraries that TubeTK depends on.<br />
** Right click on the "TubeTK" project and select "Build".<br />
<br />
==== Linux and OS X ====<br />
* Perform the initial build using your compiler at the top-level of TubeTK-Release. This will update and build the libraries that TubeTK depends on (ex. VTK, ITK), and then build TubeTK.<br />
cd $HOME/TubeTK-Release<br />
make<br />
* Subsequent builds should be initiated in the subdir TubeTK-Release/TubeTK-build to save time. This will build TubeTK only. You may have to periodically build from the top-level of TubeTK-Release to get updates to the libraries that TubeTK depends on.<br />
cd $HOME/TubeTK-Release/TubeTK-build<br />
make<br />
<br />
== 2. Have CTest do all of the remaining work ==<br />
<br><br />
<br><br />
<em> THIS METHOD IS NOT WORKING AT THIS TIME - WE NEED TO UPDATE THE BUILD FILES MENTIONED BELOW. </em><br />
<br><br />
<br><br />
<em> SORRY FOR THE INCONVENIENCE - PLEASE USE THE MANUAL BUILD METHOD DESCRIBED ABOVE</em><br />
<br><br />
<br><br />
<br />
This is the recommended approach for people who will be using and developing in TubeTK. It not only builds and tests TubeTK with minimal effort, but it also submits your build as an "experimental" on the TubeTK dashboard - this allows us to more easily help you debug errors during the build process:<br />
<br />
* Download a ctest configuration file for TubeTK<br />
:Linux: [https://github.com/TubeTK/TubeTK/blob/master/CMake/TubeTK_InitialBuild_Linux.cmake TubeTK_InitialBuild_Linux.cmake]<br />
:OS X:[https://github.com/TubeTK/TubeTK/blob/master/CMake/TubeTK_InitialBuild_Mac.cmake TubeTK_InitialBuild_Mac.cmake]<br />
:Windows: [https://github.com/TubeTK/TubeTK/blob/master/CMake/TubeTK_InitialBuild_Windows.cmake TubeTK_InitialBuild_Windows.cmake]<br />
* Edit it to match your environment<br />
** Only the variables in the first portion of the file should be edited. They are clearly marked and self explanatory. Additional details are at [[TubeTK/Dashboard Scripts]].<br />
* Run ctest and submit an experimental dashboard<br />
:Fedora and Ubuntu:<br />
:<code>ctest -S TubeTK_InitialBuild_Linux.cmake</code><br />
:Red Hat Enterprise Linux:<br />
:<code>ctest28 -S TubeTK_InitialBuild_Linux.cmake</code><br />
:OS X:<br />
:<code>ctest -S TubeTK_InitialBuild_Mac.cmake</code><br />
:Windows:<br />
:<code>ctest -S TubeTK_InitialBuild_Windows.cmake</code><br />
:This will download the source code, configure it, build it, test it, and then submit the results to the [http://open.cdash.org/index.php?project=TubeTK TubeTK Dashboard].<br />
<br />
= Advanced =<br />
<br />
== Using KWStyle ==<br />
For introductory information, see: [http://public.kitware.com/KWStyle/ http://public.kitware.com/KWStyle/].<br />
git clone http://public.kitware.com/KWStyle.git $HOME/KWStyle<br />
mkdir $HOME/KWStyle-Release<br />
cd $HOME/KWStyle-Release<br />
cmake -DCMAKE_BUILD_TYPE=Release ../KWStyle<br />
make<br />
sudo make install<br />
<br />
cd $HOME/TubeTK-Release<br />
cmake -DTubeTK_USE_KWSTYLE=ON -DKWSTYLE_EXECUTABLE=/usr/local/bin/KWStyle .<br />
make<br />
make StyleCheck<br />
<br />
== Using a pre-existing ITK, JsonCpp, or VTK installation ==<br />
You can also configure CMake variables to use an existing JsonCpp installation instead of an embedded version.<br />
cd $HOME/TubeTK-Release<br />
cmake -DUSE_SYSTEM_JSONCPP .<br />
<br />
You can also configure CMake variables to use an existing ITK or VTK installation instead of an embedded versions. This is not recommended, because of inter-dependencies that require specific version of these libraries, and built using specific options, to be used.<br />
* USE_SYSTEM_ITK: OFF<br />
** If "ON", then you can tell TubeTK to use an ITK build that is already present on your system (using the CMake variable ITK_DIR).<br />
* USE_SYSTEM_VTK: OFF<br />
** If "ON", then you can tell TubeTK to use a VTK build that is already present on your system (using the CMake variable VTK_DIR). See the warning below.<br />
<br />
* Dependency on VTK version and build options<br />
** Note that TubeTK relies on VTK from 3D Slicer (https://github.com/Slicer/VTK)<br />
** The 3D Slicer fork of VTK contains enhancements that have not yet made it into the VTK repository itself.<br />
<br />
[[Category:TubeTK|Build Instructions]]</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=TubeTK/Development&diff=55023TubeTK/Development2014-01-06T21:59:56Z<p>Xiaoxiao: </p>
<hr />
<div>__NOTITLE__<br />
__NOTOC__<br />
<br />
{| border="1" cellpadding="10" cellspacing="0"<br />
|+ [[image:TubeTK_Header.jpg|1000px|link=TubeTK]]<br />
|-<br />
| style="background:#efefef;" align="left" valign="top" width="150px" | <br />
<br />
'''[[TubeTK|Home]]'''<br />
*[[TubeTK/About|About]]<br />
*[[TubeTK/Images|Image Gallery]]<br />
*[[TubeTK/Data|Data and Publications]]<br />
<br><br />
----<br />
<br><br />
'''For Users'''<br />
* [[TubeTK/Installation|Installation]]<br />
* [[TubeTK/Documentation|Methods & Apps]]<br />
* [[TubeTK/Slicer|TubeTK with 3D Slicer]]<br />
* [[TubeTK/OsiriX|TubeTK with OsiriX]]<br />
<br><br />
----<br />
<br><br />
'''For Developers'''<br />
* [[TubeTK/Development|Development Docs]]<br />
<br><br />
----<br />
<br><br />
'''[https://github.com/TubeTK/TubeTK/issues Report Bugs<br>Request Features]'''<br />
<br><br />
<br><br />
----<br />
<br><br />
'''[[TubeTK/Contact|Contact Us]]'''<br />
<br />
| width="800px" align="left" | <br />
= Collaborative TubeTK Development =<br />
<br />
<b> Please follow these steps to build and extend TubeTK </b><br />
<br />
== 1. View the software over the web ==<br />
<br />
The source code for TubeTK is hosted on GitHub:<br />
<br />
* https://github.com/TubeTK<br />
<br />
== 2. Check on the status of TubeTK ==<br />
<br />
The TubeTK Dashboard reports on the nightly build process of TubeTK. Check this to make sure the current version of TubeTK is compiling and that the relevant tests are passing on your platform:<br />
* http://open.cdash.org/index.php?project=TubeTK<br />
<br />
== 3. Build the toolkit ==<br />
<br />
* [[TubeTK/Build Instructions|Build Instructions]]<br />
<br />
== 4. Learn and live the development guidelines ==<br />
<br />
* [https://help.github.com/articles/fork-a-repo Fork the Github repo for TubeTK]<br />
* [[TubeTK/Developers Guide|Developers Guide]]<br />
* [[TubeTK/Code Optimization in Linux|Code Optimization in Linux]]<br />
<br />
== 5. Contribute Dashboard Clients ==<br />
<br />
* [[TubeTK/Dashboard Scripts|Dashboard Scripts]]<br />
<br />
== 6. Contribute Code ==<br />
<br />
* [[TubeTK/Midas Unit Tests|Adding Midas-based Unit Tests]]<br />
<br />
== 7. Read the FAQ ==<br />
<br />
* [[TubeTK/Developers FAQ|Developers FAQ]]<br />
<br />
== 8. Join the Developers' Mailing List ==<br />
<br />
*Join the TubeTK email list here: [http://public.kitware.com/cgi-bin/mailman/listinfo/tubetk-developers]<br />
<br />
|}<br />
<br />
[[Category:TubeTK|Development]]</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=TubeTK/Development&diff=55022TubeTK/Development2014-01-06T21:59:27Z<p>Xiaoxiao: </p>
<hr />
<div>__NOTITLE__<br />
__NOTOC__<br />
<br />
{| border="1" cellpadding="10" cellspacing="0"<br />
|+ [[image:TubeTK_Header.jpg|1000px|link=TubeTK]]<br />
|-<br />
| style="background:#efefef;" align="left" valign="top" width="150px" | <br />
<br />
'''[[TubeTK|Home]]'''<br />
*[[TubeTK/About|About]]<br />
*[[TubeTK/Images|Image Gallery]]<br />
*[[TubeTK/Data|Data and Publications]]<br />
<br><br />
----<br />
<br><br />
'''For Users'''<br />
* [[TubeTK/Installation|Installation]]<br />
* [[TubeTK/Documentation|Methods & Apps]]<br />
* [[TubeTK/Slicer|TubeTK with 3D Slicer]]<br />
* [[TubeTK/OsiriX|TubeTK with OsiriX]]<br />
<br><br />
----<br />
<br><br />
'''For Developers'''<br />
* [[TubeTK/Development|Development Docs]]<br />
<br><br />
----<br />
<br><br />
'''[https://github.com/TubeTK/TubeTK/issues Report Bugs<br>Request Features]'''<br />
<br><br />
<br><br />
----<br />
<br><br />
'''[[TubeTK/Contact|Contact Us]]'''<br />
<br />
| width="800px" align="left" | <br />
= Collaborative TubeTK Development =<br />
<br />
<b> Please follow these steps to build and extend TubeTK </b><br />
<br />
== 1. View the software over the web ==<br />
<br />
The source code for TubeTK is hosted on GitHub:<br />
<br />
* https://github.com/TubeTK<br />
<br />
== 2. Check on the status of TubeTK ==<br />
<br />
The TubeTK Dashboard reports on the nightly build process of TubeTK. Check this to make sure the current version of TubeTK is compiling and that the relevant tests are passing on your platform:<br />
* http://open.cdash.org/index.php?project=TubeTK<br />
<br />
== 3. Build the toolkit ==<br />
<br />
* [[TubeTK/Build Instructions|Build Instructions]]<br />
<br />
== 4. Learn and live the development guidelines ==<br />
<br />
* [https://help.github.com/articles/fork-a-repo Fork the Github repo for TubeTK]<br />
* [[TubeTK/Developers Guide|Developers Guide]]<br />
* [[TubeTK/Code Optimization in Linux|Code Optimization in Linux]]<br />
<br />
== 5. Contribute Dashboard Clients ==<br />
<br />
* [[TubeTK/Dashboard Scripts|Dashboard Scripts]]<br />
<br />
== 6. Contribute Code ==<br />
<br />
* [[TubeTK/Midas Unit Tests|Adding Midas-based Unit Tests]]<br />
<br />
== 7. Read the FAQ ==<br />
<br />
* [[TubeTK/Developers FAQ|Developers FAQ]]<br />
<br />
<br />
== 8. Join the Developers' Mailing List ==<br />
<br />
*Join the TubeTK email list here: [http://public.kitware.com/cgi-bin/mailman/listinfo/tubetk-developers]<br />
<br />
|}<br />
<br />
[[Category:TubeTK|Development]]</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=TubeTK/Development&diff=55020TubeTK/Development2014-01-06T21:57:09Z<p>Xiaoxiao: /* Collaborative TubeTK Development */</p>
<hr />
<div>__NOTITLE__<br />
__NOTOC__<br />
<br />
{| border="1" cellpadding="10" cellspacing="0"<br />
|+ [[image:TubeTK_Header.jpg|1000px|link=TubeTK]]<br />
|-<br />
| style="background:#efefef;" align="left" valign="top" width="150px" | <br />
<br />
'''[[TubeTK|Home]]'''<br />
*[[TubeTK/About|About]]<br />
*[[TubeTK/Images|Image Gallery]]<br />
*[[TubeTK/Data|Data and Publications]]<br />
<br><br />
----<br />
<br><br />
'''For Users'''<br />
* [[TubeTK/Installation|Installation]]<br />
* [[TubeTK/Documentation|Methods & Apps]]<br />
* [[TubeTK/Slicer|TubeTK with 3D Slicer]]<br />
* [[TubeTK/OsiriX|TubeTK with OsiriX]]<br />
<br><br />
----<br />
<br><br />
'''For Developers'''<br />
* [[TubeTK/Development|Development Docs]]<br />
<br><br />
----<br />
<br><br />
'''[https://github.com/TubeTK/TubeTK/issues Report Bugs<br>Request Features]'''<br />
<br><br />
<br><br />
----<br />
<br><br />
'''[[TubeTK/Contact|Contact Us]]'''<br />
<br />
| width="800px" align="left" | <br />
= Collaborative TubeTK Development =<br />
<br />
<b> Please follow these steps to build and extend TubeTK </b><br />
<br />
== 1. View the software over the web ==<br />
<br />
The source code for TubeTK is hosted on GitHub:<br />
<br />
* https://github.com/TubeTK<br />
<br />
== 2. Check on the status of TubeTK ==<br />
<br />
The TubeTK Dashboard reports on the nightly build process of TubeTK. Check this to make sure the current version of TubeTK is compiling and that the relevant tests are passing on your platform:<br />
* http://open.cdash.org/index.php?project=TubeTK<br />
<br />
== 3. Build the toolkit ==<br />
<br />
* [[TubeTK/Build Instructions|Build Instructions]]<br />
<br />
== 4. Learn and live the development guidelines ==<br />
<br />
* [https://help.github.com/articles/fork-a-repo Fork the Github repo for TubeTK]<br />
* [[TubeTK/Developers Guide|Developers Guide]]<br />
* [[TubeTK/Code Optimization in Linux|Code Optimization in Linux]]<br />
<br />
== 5. Contribute Dashboard Clients ==<br />
<br />
* [[TubeTK/Dashboard Scripts|Dashboard Scripts]]<br />
<br />
== 6. Contribute Code ==<br />
<br />
* [[TubeTK/Midas Unit Tests|Adding Midas-based Unit Tests]]<br />
<br />
== 7. Read the FAQ ==<br />
<br />
* [[TubeTK/Developers FAQ|Developers FAQ]]<br />
|}<br />
<br />
== 8. Join the Developers' Mailing List ==<br />
<br />
*Join the TubeTK email list here:<br />
http://public.kitware.com/cgi-bin/mailman/listinfo/tubetk-developers<br />
<br />
<br />
[[Category:TubeTK|Development]]</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK/Release_4/Modularization/Add_an_external_module_(external_module)&diff=54125ITK/Release 4/Modularization/Add an external module (external module)2013-09-17T17:07:43Z<p>Xiaoxiao: /* Testing data */</p>
<hr />
<div>=== Synopsis ===<br />
<br />
An External Module is distributed outside the ITK main repository, but it could be built into ITK as a module once downloaded into the local copy of ITK source tree.<br />
<br />
=== Organization ===<br />
<br />
The organization of an External Module should be the same as an Internal Module: <br />
[[ITK_Release_4/Modularization/ Add a module|Add a module (Internal Module)]]<br />
<br />
To build an External Module, users download it into a local copy of ITK source tree under: ''ITK/Modules/External/''. Then simply rerun the CMake step to configure the new External Module together with other enabled ITK modules.<br />
<br />
<br />
==== External Module Template ====<br />
<br />
Here is a module template for your convenience to build your own module (thanks to Bradley Lowekamp), along with instructions:<br />
* https://github.com/blowekamp/itkExternalTemplate<br />
<br />
<br />
==== Testing data ====<br />
<br />
Testing data, such an input and baseline images, are typically kept outside of the Git repository to keep the repository small.<br />
<br />
The ITK method for handling test data is the [[ITK/Git/Develop/Data#ExternalData | CMake/ExternalData]] method, where MD5 hashes of the data are stored in the repository, then the files corresponding to the hashes are fetched at build time from a list of data servers. These data servers can be an Apache server you have at your webhost, a [http://midasplatform.org/ Midas server], a Dropbox account, an Amazon S3 account, a Rackspace Cloud File account, etc.<br />
<br />
To use the ExternalData mechanism with your own data server:<br />
<br />
# Add testing data references in you ''test/CMakeLists.txt'' as you normally would, i.e. use '''itk_add_test''' and with '''DATA{Baseline/image.mha}'''.<br />
# As usual, copy the image to its location specified within ''DATA{}''.<br />
# As usual, next time ''cmake'' is executed, a message will appear like: ''Linked Modules/External/ITKMyNewModule/test/Baseline/image.mha.md5 to ExternalData MD5/a3519cb25bb2afeda999378a2f8103cc''<br />
# Copy the file ''test/Baseline/.ExternalData_MD5_a3519cb25bb2afeda999378a2f8103cc'' to a location on your publically available data server, such as ''http://www.example.com/ITKExternalData/MD5/a3519cb25bb2afeda999378a2f8103cc''.<br />
# In your ITK CMake configuration, set the value of ''ExternalData_URL_TEMPLATES'' to ''http://www.example.com/ITKExternalData/%(algo)/%(hash)''<br />
<br />
=== Community dissemination ===<br />
<br />
An example is demonstrated in the Lesion Sizing Toolkit: [http://public.kitware.com/LesionSizingKit/index.php/Users/Build_LST_as_ITK_module Lesion Sizing Toolkit Wiki]<br />
<br />
Once you have your External Module, you can make it available as a [[ITK/Policy_and_Procedures_for_Adding_Remote_Modules| Remote Module]] so it has broader exposure to the ITK community.</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK/Release_4/Modularization/Configure_and_build_ITK&diff=54091ITK/Release 4/Modularization/Configure and build ITK2013-09-05T18:50:12Z<p>Xiaoxiao: </p>
<hr />
<div>= CMake options to customizing ITK modules =<br />
<br />
== Default mode ==<br />
<br />
* '''ITK_BUILD_ALL_MODULES''': request to build all the default modules in the toolkit, by default this option is ON.<br />
All non-default modules have "EXCLUCDE_FROM_ALL" tags in their module definition files(itk-module.cmake), including the remote modules (source<br />
code located outside of the main ITK repository) and modules who depend on external third-party libraries, such as vtkGlue, BridgeOpenCV, BridgeVXL, etc.<br />
<br />
<br />
== Group Options==<br />
<br />
* '''ITKGroup<xxx>''': request to build a group of modules. The source code is organized as such that modules belong to the same group stay in the same group directory. The core group is turned on by default.<br />
<br />
When a group is ON, all the modules in the group and their depending modules are enabled. When a group of OFF, all the modules in the group except the ones that are required by other enabled modules.<br />
<br />
<br />
== Module Options ==<br />
* '''Module_<xxx>''': request to build a module. This option is hidden from the CMake gui when the module is enabled by module dependencies (other modules depend on this module), by the the group option or by the default mode(ITK_BUILD_ALL_MODULES).</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK/Release_4/Modularization/Configure_and_build_ITK&diff=54080ITK/Release 4/Modularization/Configure and build ITK2013-09-04T05:21:40Z<p>Xiaoxiao: </p>
<hr />
<div>= CMake options to customizing ITK modules =<br />
<br />
== Default mode ==<br />
<br />
* '''ITK_BUILD_ALL_MODULES''': request to build all the default modules in the toolkit, by default this option is ON.<br />
All non-default modules have "EXCLUCDE_FROM_ALL" tags in their module definition files(itk-module.cmake), including the remote modules (source<br />
code located outside of the main ITK repository) and modules who depend on external third-party libraries, such as vtkGlue, BridgeOpenCV, BridgeVXL, etc.<br />
<br />
<br />
== Group Options==<br />
<br />
* '''ITKGroup<xxx>''': request to build a group of modules. The source code is organized as such that modules belong to the same group stay in the same group directory. The core group is turned on by default.<br />
<br />
When a group is ON, all the modules in the group and their depending modules are enabled. When a group of OFF, all the modules in the group except the ones that are required by other enabled modules.<br />
<br />
<br />
== Module Options ==<br />
* '''Module_<xxx>''': request to build a module. This option is hidden from the CMake gui when the module is enabled by either by module dependencies (other modules depend on this module), or by the the group option or the default mode.</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK/Release_4/Modularization/_Add_tests&diff=54073ITK/Release 4/Modularization/ Add tests2013-09-03T20:20:14Z<p>Xiaoxiao: </p>
<hr />
<div>== Non-regression tests ==<br />
<br />
The same way it used to be, except the newer syntax in "add_test" command:<br />
<br />
{{#tag:syntaxhighlight<br />
|<br />
<br />
add_executable(itkBinaryThresholdFilterTest itkBinaryThresholdFilterTest.cxx)<br />
<br />
target_link_libraries(itkBinaryThresholdFilterTest ${ITK-BinaryThreshold_LIBRARIES})<br />
<br />
# adopt the modern CMake syntax :[NAME, COMMAND]<br />
<br />
itk_add_test(NAME itkBinaryThresholdFilterTest <br />
COMMAND itkBinaryThresholdFilterTest input.png output.png)<br />
|lang=cmake}}<br />
<br />
<br />
<br />
== Regression tests ==<br />
<br />
=== Approach A ===<br />
<br />
Using the test driver macro<br />
The CMake macro "CreateTestDriver" defined in <br />
<br />
Module/Core/TestKernal/CreateTestDriver.cmake<br />
<br />
is designed for grouped regression tests in ITK. <br />
<br />
All the tests in one module share one test driver.<br />
<br />
{{#tag:syntaxhighlight<br />
|<br />
<br />
set(ITKFooFilterTests<br />
itkFooFilterTest1.cxx<br />
itkFooFilterTest2.cxx)<br />
<br />
CreateTestDriver(ITKFooFilter "${ITK_FooFilter-Test_LIBRARIES}" "${ITK-FooFilterTest}")<br />
<br />
itk_add_test(NAME itkFooFilterTest1<br />
COMMAND ITKFooFilterTestDriver itkFooFilterTest1)<br />
<br />
itk_add_test(NAME itkFooFilterTest2<br />
COMMAND ITKFooFilterTestDriver itkFooFilterTest2)<br />
<br />
<br />
|lang=cmake}}<br />
<br />
<br />
You can find Approach A used in most of the ITK modules.<br />
for example in<br />
<br />
ITK/Modules/IO/BMP/test/CMakeLists.txt<br />
<br />
=== Approach B ===<br />
<br />
Stand-alone regression tests<br />
<br />
There is also a test driver executable("itkTestdriver") designed for stand-alone regression tests. For instance, all the tests in Examples are stand-alone programs each has its own main function call, in which case, the approach A is not appropriate.<br />
<br />
<br />
{{#tag:syntaxhighlight<br />
|<br />
add_exectuable(itkFooTest itkFooTest.cxx)<br />
<br />
target_line_libraries( itkFooTest ${ITK_LIBRARIES})<br />
<br />
itk_add_test(NAME itkFooTest<br />
COMMAND itkTestDriver<br />
--compare outputBaseline.png output.png<br />
'''$<TARGET_FILE:'''itkFooFilterTest'''>''' input.png output.png)<br />
|lang=cmake}}<br />
<br />
<br />
The new syntax<br />
<br />
$<TARGET_FILE: xxx> <br />
<br />
in the add_test command triggers CMake to locate the executable automatically. No need to specify the path for the executable here.<br />
<br />
You can find Approach B used in Examples.<br />
<br />
For example in<br />
<br />
ITK/Examples/Filtering/test/CMakeLists.txt<br />
<br />
<br />
== Add testing data to ITK ==<br />
Please refer to: [http://www.itk.org/Wiki/index.php?title=ITK/Git/Develop/Data&oldid=41775 | Add Data]</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK/Release_4/Modularization/Modular_Dashboard&diff=54072ITK/Release 4/Modularization/Modular Dashboard2013-09-03T20:18:04Z<p>Xiaoxiao: /* Modular Dashboard */</p>
<hr />
<div>= Modular Dashboard =<br />
*ITK Modular dashboard is no longer in use. Maybe we will use a modular dashboard for remote modules only.<br />
<br />
<br />
<br />
<br />
The following is the historical discussion:<br />
== Bugs ? ==<br />
<br />
* Dynamic analysis doesn't show up in the summary page of the toolkit.<br />
** http://www.cdash.org/CDash/index.php?project=ITKModular&display=project<br />
* The main dashboard shows 75 errors. Now I realize that this is a machine count. However, to investigate the errors, I click on [http://www.cdash.org/CDash/index.php?project=ITKModular&subproject=ITK-CurvatureFlow ITK-CurvatureFlow]. I see one machine with 156 compile errors. Now, I go to look at the next module:[http://www.cdash.org/CDash/index.php?project=ITKModular&subproject=ITK-TestKernel ITK-TestKernel] which shows the same 156 compile errors. IOBase is the same. In fact most (I did not bother visiting every module page) pages report the same errors.<br />
* Navigate from the top level to [http://www.cdash.org/CDash/index.php?project=ITKModular&display=project here]. Although the page looks similar to the old top level page,<br />
** none of the counts are hyper-linked<br />
** there are many '-1's'<br />
** in the Continuous section, some numbers are linked and some are not<br />
* Navigation error<br />
** Go [http://www.cdash.org/CDash/index.php?project=ITKModular&subproject=ITK-VNL&date=2011-04-22 here].<br />
** Then go [http://www.cdash.org/CDash/viewBuildError.php?type=1&buildid=1003683 here].<br />
** Clicking on the cdash Back button, ends up [http://www.cdash.org/CDash/index.php?project=ITKModular&date=2011-04-22 here] rather than [http://www.cdash.org/CDash/index.php?project=ITKModular&subproject=ITK-VNL&date=2011-04-22 the page we came from].<br />
* Missing Back button.<br />
** Starting from the [http://www.cdash.org/CDash/index.php?project=ITKModular&date= main dashboard].<br />
** Navigate [http://www.cdash.org/CDash/index.php?project=ITKModular&display=project here].<br />
** There is no Back button. It is easy not to notice this and hit the "Previous" button instead, which goes to the same page, but the [http://www.cdash.org/CDash/index.php?project=ITKModular&date=2011-04-21&display=project previous day].<br />
<br />
= Desired Features =<br />
<br />
* There is no way to move or hide the Sub Projects section. See this [http://www.cdash.org/CDash/index.php?project=ITKModular&subproject=ITK-IntegratedTest example].<br />
* The counts on the main dashboard are inconsistent. In the SubProjects<br />
** the Configure numbers refer to machine counts<br />
** the Build numbers refer to machine counts<br />
** the Test numbers refer to number of tests<br />
* It would be great if one could select the old format using an alternate http: link or a button on the top page. This would certainly help the transition and also allow developers a choice of presentations.<br />
<br />
= Speed =<br />
<br />
Please separate speed and performance issues from actual features.<br />
* Kitware is getting a virtual cluster machine to replace the current Dashboard server, so it is anticipated that this hardware replacement will take care of speed and performance issues.<br />
* The performance is much slower than the original dashboard. For example [http://www.cdash.org/CDash/index.php?project=ITKModular&date= this new page] took 47 seconds to load while [http://www.cdash.org/CDash/index.php?project=Insight this old page] took 1.1 seconds. New is about 40 times slower than old. Even with a server upgrade the performance will be slower than the old dashboard.<br />
<br />
= Individual Observations =<br />
* Lorensen: My initial impression of the itk modular dashboard is that is not in a form that is usable for ITK at this time. The navigation is cumbersome and it is difficult to use on a day-to-day basis. I hope we can have more discussion about this.<br />
** Proposal<br />
*** Try the new format for two weeks.<br />
*** Gather feedback on this page.<br />
*** Poll the developers with a go/nogo.<br />
*** If go, convert current submissions to the new format.<br />
*** If nogo, revert all submissions to the non-modular dashboard and wait for a new cdash release.<br />
<br />
* Luis: Please phrase this into actionable items or actual well-defined desired features, so we can have a productive discussion.<br />
<br />
* Brad L: I have concerns about the performance beyond just the machine. As I do not know if there is IO, or CPU issues my observation is rather general. The response is slow and it appears to do a significant amount of work to load a page, even reloading it a moment later. I wonder if there a a better way to do some type of caching to reduce the computation needed.<br />
<br />
= How We are Addressing These Concerns =<br />
<br />
== New Hardware ==<br />
<br />
* We will be replacing the Dashboard server with new hardware, a virtual cluster, that should be online several weeks from now.<br />
* This new hardware will improve the performance, but, as some of you already pointed out, it may or many not be enough to fully address the responsiveness of the web pages.<br />
<br />
== Workarounds ==<br />
<br />
* Follow [http://www.cdash.org/CDash/index.php?project=ITKModular&display=project&collapse=0&filtercount=6&showfilters=1&filtercombine=or&field1=configureerrors/number&compare1=43&value1=0&field2=configurewarnings/number&compare2=43&value2=0&field3=builderrors/number&compare3=43&value3=0&field4=buildwarnings/number&compare4=43&value4=0&field5=testsfailed/number&compare5=43&value5=0&field6=testsnotrun/number&compare6=43&value6=0&collapse=0 this link] to view all non-green subproject submissions.<br />
<br />
== Step Back to Monolithic Dashboard ==<br />
<br />
* For the purpose of maintaining the rhythm of the development team, we suggest to step back to the Monolithic Dashboard, while in parallel we continue working on the Modular dashboard to make it a useful tool for the ITK developers community.<br />
* Essential builds should be reconfigured back to submit to the Monolithic Dashboard. In particular<br />
** Code coverage builds<br />
** Valgrind builds<br />
** Unusual platforms<br />
*** MinGW<br />
*** SunCC<br />
* A number of builds should still be submitting to the Modular dashboard, so we have a realistic load to experiment with new organization of the queries and change modifications to CDash. Probably 20 to 30 submissions would be enough for this purpose.<br />
<br />
== Use Cases ==<br />
<br />
* We need to gather use cases of Modular Dashboard usage, in order to ensure that we provide efficient access to them.<br />
* Some examples are provided below.<br />
* Please help us gather more.<br />
<br />
=== Case 1 ===<br />
<br />
* What is broken today ?<br />
** This is the common question of a developer who merged some changes yesterday, and quickly want to see if any of them broke anything in the Dashboard<br />
<br />
=== Case 2 ===<br />
<br />
* What is broken in this platform ?<br />
<br />
=== Case 3 ===<br />
<br />
* In what platforms is Test X failing ?<br />
<br />
=== Case 4 ===<br />
<br />
* When did Test X start failing ?<br />
<br />
=== Case 5 ===<br />
<br />
* What is the code coverage of Module X ?<br />
<br />
=== Case 6 ===<br />
<br />
* Are there any valgrind issues today ?</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK/Release_4/Modularization/Modular_Dashboard&diff=54071ITK/Release 4/Modularization/Modular Dashboard2013-09-03T20:17:41Z<p>Xiaoxiao: /* Modular Dashboard */</p>
<hr />
<div>= Modular Dashboard =<br />
ITK Modular dashboard is no longer in use. Maybe we will use a modular dashboard for remote modules only.<br />
<br />
<br />
<br />
<br />
The following is the historical discussion:<br />
== Bugs ? ==<br />
<br />
* Dynamic analysis doesn't show up in the summary page of the toolkit.<br />
** http://www.cdash.org/CDash/index.php?project=ITKModular&display=project<br />
* The main dashboard shows 75 errors. Now I realize that this is a machine count. However, to investigate the errors, I click on [http://www.cdash.org/CDash/index.php?project=ITKModular&subproject=ITK-CurvatureFlow ITK-CurvatureFlow]. I see one machine with 156 compile errors. Now, I go to look at the next module:[http://www.cdash.org/CDash/index.php?project=ITKModular&subproject=ITK-TestKernel ITK-TestKernel] which shows the same 156 compile errors. IOBase is the same. In fact most (I did not bother visiting every module page) pages report the same errors.<br />
* Navigate from the top level to [http://www.cdash.org/CDash/index.php?project=ITKModular&display=project here]. Although the page looks similar to the old top level page,<br />
** none of the counts are hyper-linked<br />
** there are many '-1's'<br />
** in the Continuous section, some numbers are linked and some are not<br />
* Navigation error<br />
** Go [http://www.cdash.org/CDash/index.php?project=ITKModular&subproject=ITK-VNL&date=2011-04-22 here].<br />
** Then go [http://www.cdash.org/CDash/viewBuildError.php?type=1&buildid=1003683 here].<br />
** Clicking on the cdash Back button, ends up [http://www.cdash.org/CDash/index.php?project=ITKModular&date=2011-04-22 here] rather than [http://www.cdash.org/CDash/index.php?project=ITKModular&subproject=ITK-VNL&date=2011-04-22 the page we came from].<br />
* Missing Back button.<br />
** Starting from the [http://www.cdash.org/CDash/index.php?project=ITKModular&date= main dashboard].<br />
** Navigate [http://www.cdash.org/CDash/index.php?project=ITKModular&display=project here].<br />
** There is no Back button. It is easy not to notice this and hit the "Previous" button instead, which goes to the same page, but the [http://www.cdash.org/CDash/index.php?project=ITKModular&date=2011-04-21&display=project previous day].<br />
<br />
= Desired Features =<br />
<br />
* There is no way to move or hide the Sub Projects section. See this [http://www.cdash.org/CDash/index.php?project=ITKModular&subproject=ITK-IntegratedTest example].<br />
* The counts on the main dashboard are inconsistent. In the SubProjects<br />
** the Configure numbers refer to machine counts<br />
** the Build numbers refer to machine counts<br />
** the Test numbers refer to number of tests<br />
* It would be great if one could select the old format using an alternate http: link or a button on the top page. This would certainly help the transition and also allow developers a choice of presentations.<br />
<br />
= Speed =<br />
<br />
Please separate speed and performance issues from actual features.<br />
* Kitware is getting a virtual cluster machine to replace the current Dashboard server, so it is anticipated that this hardware replacement will take care of speed and performance issues.<br />
* The performance is much slower than the original dashboard. For example [http://www.cdash.org/CDash/index.php?project=ITKModular&date= this new page] took 47 seconds to load while [http://www.cdash.org/CDash/index.php?project=Insight this old page] took 1.1 seconds. New is about 40 times slower than old. Even with a server upgrade the performance will be slower than the old dashboard.<br />
<br />
= Individual Observations =<br />
* Lorensen: My initial impression of the itk modular dashboard is that is not in a form that is usable for ITK at this time. The navigation is cumbersome and it is difficult to use on a day-to-day basis. I hope we can have more discussion about this.<br />
** Proposal<br />
*** Try the new format for two weeks.<br />
*** Gather feedback on this page.<br />
*** Poll the developers with a go/nogo.<br />
*** If go, convert current submissions to the new format.<br />
*** If nogo, revert all submissions to the non-modular dashboard and wait for a new cdash release.<br />
<br />
* Luis: Please phrase this into actionable items or actual well-defined desired features, so we can have a productive discussion.<br />
<br />
* Brad L: I have concerns about the performance beyond just the machine. As I do not know if there is IO, or CPU issues my observation is rather general. The response is slow and it appears to do a significant amount of work to load a page, even reloading it a moment later. I wonder if there a a better way to do some type of caching to reduce the computation needed.<br />
<br />
= How We are Addressing These Concerns =<br />
<br />
== New Hardware ==<br />
<br />
* We will be replacing the Dashboard server with new hardware, a virtual cluster, that should be online several weeks from now.<br />
* This new hardware will improve the performance, but, as some of you already pointed out, it may or many not be enough to fully address the responsiveness of the web pages.<br />
<br />
== Workarounds ==<br />
<br />
* Follow [http://www.cdash.org/CDash/index.php?project=ITKModular&display=project&collapse=0&filtercount=6&showfilters=1&filtercombine=or&field1=configureerrors/number&compare1=43&value1=0&field2=configurewarnings/number&compare2=43&value2=0&field3=builderrors/number&compare3=43&value3=0&field4=buildwarnings/number&compare4=43&value4=0&field5=testsfailed/number&compare5=43&value5=0&field6=testsnotrun/number&compare6=43&value6=0&collapse=0 this link] to view all non-green subproject submissions.<br />
<br />
== Step Back to Monolithic Dashboard ==<br />
<br />
* For the purpose of maintaining the rhythm of the development team, we suggest to step back to the Monolithic Dashboard, while in parallel we continue working on the Modular dashboard to make it a useful tool for the ITK developers community.<br />
* Essential builds should be reconfigured back to submit to the Monolithic Dashboard. In particular<br />
** Code coverage builds<br />
** Valgrind builds<br />
** Unusual platforms<br />
*** MinGW<br />
*** SunCC<br />
* A number of builds should still be submitting to the Modular dashboard, so we have a realistic load to experiment with new organization of the queries and change modifications to CDash. Probably 20 to 30 submissions would be enough for this purpose.<br />
<br />
== Use Cases ==<br />
<br />
* We need to gather use cases of Modular Dashboard usage, in order to ensure that we provide efficient access to them.<br />
* Some examples are provided below.<br />
* Please help us gather more.<br />
<br />
=== Case 1 ===<br />
<br />
* What is broken today ?<br />
** This is the common question of a developer who merged some changes yesterday, and quickly want to see if any of them broke anything in the Dashboard<br />
<br />
=== Case 2 ===<br />
<br />
* What is broken in this platform ?<br />
<br />
=== Case 3 ===<br />
<br />
* In what platforms is Test X failing ?<br />
<br />
=== Case 4 ===<br />
<br />
* When did Test X start failing ?<br />
<br />
=== Case 5 ===<br />
<br />
* What is the code coverage of Module X ?<br />
<br />
=== Case 6 ===<br />
<br />
* Are there any valgrind issues today ?</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK/Release_4/Modularization/Configure_and_build_ITK&diff=54070ITK/Release 4/Modularization/Configure and build ITK2013-09-03T20:13:06Z<p>Xiaoxiao: /* Key CMake options created for modular ITK */</p>
<hr />
<div>= CMake options to customizing ITK modules =<br />
<br />
== Default mode ==<br />
<br />
* '''ITK_BUILD_ALL_MODULES''': request to build all the default modules in the toolkit, by default this option is ON.<br />
All non-default modules have "EXCLUCDE_FROM_ALL" tags in their module definition files(itk-module.cmake), including the remote modules (source<br />
code located outside of the main ITK repository) and modules who depend on external third-party libraries, such as vtkGlue, BridgeOpenCV, BridgeVXL, etc.<br />
<br />
<br />
== Group mode ==<br />
<br />
* '''ITKGroup<xxx>''': select a group of modules. The default grouping/categorization of the modules can be found in "ITK/CMake/ITKGroup.cmake". The core group is turned on by default.<br />
<br />
When a group is ON, all the modules in the group and their depending modules are enabled as well.<br />
<br />
<br />
== Advanced mode (modules) ==<br />
* '''Module_<xxx>''': request to build a module.</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK/Release_4/Modularization/Configure_and_build_ITK&diff=54069ITK/Release 4/Modularization/Configure and build ITK2013-09-03T20:06:57Z<p>Xiaoxiao: /* Advanced mode (modules) */</p>
<hr />
<div>= Key CMake options created for modular ITK =<br />
<br />
== Main mode (groups) ==<br />
* '''ITKGroup<xxx>''': select a group of modules. The default grouping/categorization of the modules can be found in "ITK/CMake/ITKGroup.cmake". The core group is turned on by default.<br />
<br />
When a group is ON, all the modules in the group and their depending modules are "enabled".<br />
<br />
== Advanced mode (modules) ==<br />
* '''Module_<xxx>''': request to build a module.<br />
* '''ITK_BUILD_ALL_MODULES''': build all the modules in the toolkit (for testing the entire toolkit, this option is often used)<br />
When a module is ON, the module and its depending modules are "enabled".</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK/Release_4/Modularization/Configure_and_build_ITK&diff=54068ITK/Release 4/Modularization/Configure and build ITK2013-09-03T20:06:12Z<p>Xiaoxiao: /* Main mode (groups) */</p>
<hr />
<div>= Key CMake options created for modular ITK =<br />
<br />
== Main mode (groups) ==<br />
* '''ITKGroup<xxx>''': select a group of modules. The default grouping/categorization of the modules can be found in "ITK/CMake/ITKGroup.cmake". The core group is turned on by default.<br />
<br />
When a group is ON, all the modules in the group and their depending modules are "enabled".<br />
<br />
== Advanced mode (modules) ==<br />
* '''Module_<xxx>''': build a module.<br />
* '''ITK_BUILD_ALL_MODULES''': build all the modules in the toolkit (for testing the entire toolkit, this option is often used)<br />
When a module is ON, the module and its depending modules are "enabled".<br />
The corresponding CMake variables " <module name>_ENABLED" are ON.</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK_Release_4/Video/HowToBuildVideoModules&diff=54063ITK Release 4/Video/HowToBuildVideoModules2013-09-03T16:08:30Z<p>Xiaoxiao: </p>
<hr />
<div>There are five video modules in ITKv4 at the moment: Core, Filtering, IO, BridgeOpenCV and BridgeOpenVXL.<br />
<br />
The first three modules(Core, Filtering and IO) do not depend on third party libraries.<br />
By default (when ITK_BUILD_ALL_MODULES is ON), the three modules are included in the build tree.<br />
<br />
However, if you want to use BridgeOpenCV and BridgeOpenVXL, make sure you have the newer versions<br />
of OpenCV and VXl installed on your system with the following instructions:<br />
<br />
== Build BridgeOpenCV ==<br />
1. Build OpenCV:<br />
We recommend to use opencv 2.4.2 or later.<br />
Get the source code using Git:<br />
git clone git@github.com:Itseez/opencv.git<br />
git checkout 2.4.2<br />
Use CMake to build opencv with the following configuration:<br />
BUILD_EXAMPLES = OFF<br />
BUILD_TESTS = OFF<br />
WITH_FFMPEG = ON<br />
<br />
2. Enable BridgeOpenCV module when configuring ITK in CMake:<br />
Module_ITKVideoBridgeOpenCV = ON (need to manually toggle this option ON)<br />
Then, set system library Paths for OpenCV accordingly:<br />
OpenCV_DIR = <the path where you build the OpenCV><br />
<br />
<br />
<br />
<br />
== Build BridgeVXL ==<br />
1. Build VXL: <br />
svn co https://vxl.svn.sourceforge.net/svnroot/vxl/trunk vxl<br />
The revision number tested is 34805 ( 2012-04-23). Later version should work (not validated).<br />
Use CMake to build opencv with the following configuration:<br />
BUILD_EXAMPLES = OFF<br />
BUILD_DOCUMENTATION = OFF<br />
The minimum libraries needed in VXL configuration to build<br />
ITKVideoBridgeVXL are:<br />
BUILD_CORE_VIDEO = ON<br />
BUILD_CORE_UTILITIES = ON (contains vil)<br />
BUILD_CORE_IMAGING = ON (contains vul)<br />
BUILD_CORE_NUMERICS = ON (contains vnl)<br />
Also make sure you have FFMPEG installed that the following paths were found:<br />
FFMPEG_avcodec_LIBRARY<br />
FFMPEG_avformat_LIBRARY<br />
FFMPEG_avutil_LIBRARY<br />
FFMPEG_swscale_LIBRARY<br />
<br />
2. Enable BridgeOpenVXL when configuring ITK in CMake:<br />
Module_ITKVideoBridgeVXL = ON (need to manually toggle this option ON)<br />
Then, set system library Paths for VXL accordingly :<br />
VXL_DIR = <the path where you build the VXL><br />
<br />
<br />
== Dashboard submission ==<br />
Currently, there is a linux nightly dashboard submission in [http://open.cdash.org/index.php?project=Insight].<br />
Search for "Ubuntu-gcc-Release-Video" on the build name.</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK_Release_4/Video/HowToBuildVideoModules&diff=54062ITK Release 4/Video/HowToBuildVideoModules2013-09-03T16:05:58Z<p>Xiaoxiao: </p>
<hr />
<div>There are five video modules in ITKv4 at the moment: Core, Filtering, IO, BridgeOpenCV and BridgeOpenVXL.<br />
<br />
The first three modules(Core, Filtering and IO) do not depend on third party libraries.<br />
By default (when ITK_BUILD_ALL_MODULES is ON), the three modules are included in the build tree.<br />
<br />
However, if you want to use BridgeOpenCV and BridgeOpenVXL, Make sure you have the newer versions<br />
of OpenCV and VXl installed on your system with the following instructions:<br />
<br />
== Build BridgeOpenCV ==<br />
1. Build OpenCV:<br />
We recommend to use opencv 2.4.2 or later.<br />
Get the source code using Git:<br />
git clone git@github.com:Itseez/opencv.git<br />
git checkout 2.4.2<br />
Use CMake to build opencv with the following configuration:<br />
BUILD_EXAMPLES = OFF<br />
BUILD_TESTS = OFF<br />
WITH_FFMPEG = ON<br />
<br />
2. Enable BridgeOpenCV module when configuring ITK in CMake:<br />
Module_ITKVideoBridgeOpenCV = ON (need to manually toggle this option ON)<br />
Then, set system library Paths for OpenCV accordingly:<br />
OpenCV_DIR = <the path where you build the OpenCV><br />
<br />
<br />
<br />
<br />
== Build BridgeVXL ==<br />
1. Build VXL: <br />
svn co https://vxl.svn.sourceforge.net/svnroot/vxl/trunk vxl<br />
The revision number tested is 34805 ( 2012-04-23). Later version should work (not validated).<br />
Use CMake to build opencv with the following configuration:<br />
BUILD_EXAMPLES = OFF<br />
BUILD_DOCUMENTATION = OFF<br />
The minimum libraries needed in VXL configuration to build<br />
ITKVideoBridgeVXL are:<br />
BUILD_CORE_VIDEO = ON<br />
BUILD_CORE_UTILITIES = ON (contains vil)<br />
BUILD_CORE_IMAGING = ON (contains vul)<br />
BUILD_CORE_NUMERICS = ON (contains vnl)<br />
Also make sure you have FFMPEG installed that the following paths were found:<br />
FFMPEG_avcodec_LIBRARY<br />
FFMPEG_avformat_LIBRARY<br />
FFMPEG_avutil_LIBRARY<br />
FFMPEG_swscale_LIBRARY<br />
<br />
2. Enable BridgeOpenVXL when configuring ITK in CMake:<br />
Module_ITKVideoBridgeVXL = ON (need to manually toggle this option ON)<br />
Then, set system library Paths for VXL accordingly :<br />
VXL_DIR = <the path where you build the VXL></div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK_Release_4/Video/HowToBuildVideoModules&diff=54061ITK Release 4/Video/HowToBuildVideoModules2013-09-03T16:04:28Z<p>Xiaoxiao: </p>
<hr />
<div>There are five video modules in ITKv4 at the moment: Core, Filtering, IO, BridgeOpenCV and BridgeOpenVXL.<br />
<br />
The first three modules(Core, Filtering and IO) do not depend on third party libraries.<br />
By default (when ITK_BUILD_ALL_MODULES is ON), the three modules are included in the build tree.<br />
<br />
However, if you want to use BridgeOpenCV and BridgeOpenVXL, Make sure you have the newer versions<br />
of OpenCV and VXl installed on your system with the following instructions:<br />
<br />
== Build BridgeOpenCV ==<br />
1. Build OpenCV:<br />
We recommend to use opencv 2.4.2 or later.<br />
Get the source code using Git:<br />
git clone git@github.com:Itseez/opencv.git<br />
git checkout 2.4.2<br />
Use CMake to build opencv with the following configuration:<br />
BUILD_EXAMPLES = OFF<br />
BUILD_TESTS = OFF<br />
WITH_FFMPEG = ON<br />
<br />
2. Enable BridgeOpenCV module when configuring ITK in CMake:<br />
Module_ITKVideoBridgeOpenCV = ON (need to manually toggle this option ON)<br />
Then, set system library Paths for OpenCV accordingly:<br />
OpenCV_DIR = <the path where you build the OpenCV><br />
<br />
<br />
== Build BridgeVXL ==<br />
1. Build VXL: <br />
svn co https://vxl.svn.sourceforge.net/svnroot/vxl/trunk vxl<br />
The revision number tested is 34805 ( 2012-04-23). Later version should work (not validated).<br />
Use CMake to build opencv with the following configuration:<br />
BUILD_EXAMPLES = OFF<br />
BUILD_DOCUMENTATION = OFF<br />
The minimum libraries needed in VXL configuration to build<br />
ITKVideoBridgeVXL are:<br />
BUILD_CORE_VIDEO = ON<br />
BUILD_CORE_UTILITIES = ON (contains vil)<br />
BUILD_CORE_IMAGING = ON (contains vul)<br />
BUILD_CORE_NUMERICS = ON (contains vnl)<br />
Also make sure you have FFMPEG installed that the following paths were found:<br />
FFMPEG_avcodec_LIBRARY<br />
FFMPEG_avformat_LIBRARY<br />
FFMPEG_avutil_LIBRARY<br />
FFMPEG_swscale_LIBRARY<br />
<br />
2. Enable BridgeOpenVXL when configuring ITK in CMake:<br />
Module_ITKVideoBridgeVXL = ON (need to manually toggle this option ON)<br />
Then, set system library Paths for VXL accordingly :<br />
VXL_DIR = <the path where you build the VXL></div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK_Release_4/Video/HowToBuildVideoModules&diff=54060ITK Release 4/Video/HowToBuildVideoModules2013-09-03T15:50:31Z<p>Xiaoxiao: </p>
<hr />
<div>Make sure you have the newer versions of OpenCV and VXl installed on your system<br />
with the following instructions:<br />
<br />
1. Build OpenCV:<br />
We recommend to use opencv 2.4.2 or later.<br />
<br />
Get the source code using Git:<br />
git clone git@github.com:Itseez/opencv.git<br />
git checkout 2.4.2<br />
Use CMake to build opencv with the following configuration:<br />
BUILD_EXAMPLES = OFF<br />
BUILD_TESTS = OFF<br />
WITH_FFMPEG = ON<br />
<br />
<br />
2. Build VXL: <br />
svn co https://vxl.svn.sourceforge.net/svnroot/vxl/trunk vxl<br />
The revision number tested is 34805 ( 2012-04-23). Later version should work (but not tested).<br />
se CMake to build opencv with the following configuration:<br />
BUILD_EXAMPLES = OFF<br />
BUILD_DOCUMENTATION = OFF<br />
The minimum libraries needed in VXL configuration to build<br />
ITKVideoBridgeVXL are:<br />
BUILD_CORE_VIDEO = ON<br />
BUILD_CORE_UTILITIES = ON (contains vil)<br />
BUILD_CORE_IMAGING = ON (contains vul)<br />
BUILD_CORE_NUMERICS = ON (contains vnl)<br />
Also make sure you have FFMPEG installed that the following paths were found :<br />
FFMPEG_avcodec_LIBRARY<br />
FFMPEG_avformat_LIBRARY<br />
FFMPEG_avutil_LIBRARY<br />
FFMPEG_swscale_LIBRARY<br />
<br />
<br />
<br />
3. Enable Video modules when configure ITK in CMake:<br />
Module_ITKVideoCore = ON (turn on by default)<br />
Module_ITKVideoFiltering = ON (turn on by default)<br />
Module_ITKVideoIO = ON (turn on by default)<br />
Module_ITKVideoBridgeOpenCV = ON (need to manually toggle this option ON)<br />
Module_ITKVideoBridgeVXL =ON (need to manually toggle this option ON)<br />
Then, set system library Paths for OpenCV and VXL accordingly:<br />
OpenCV_DIR = <the path where you build the OpenCV><br />
VXL_DIR = <the path where you build the VXL></div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK_Release_4/Video/HowToBuildVideoModules&diff=54052ITK Release 4/Video/HowToBuildVideoModules2013-09-02T16:31:54Z<p>Xiaoxiao: Created page with "Make sure you have the newer versions of OpenCV and VXl installed on your system with the following instructions: 1. Build OpenCV: We recommend to use opencv 2.4.2 or later. Ge..."</p>
<hr />
<div>Make sure you have the newer versions of OpenCV and VXl installed on your system<br />
with the following instructions:<br />
<br />
1. Build OpenCV:<br />
We recommend to use opencv 2.4.2 or later.<br />
<br />
Get the source code using Git:<br />
git clone git@github.com:Itseez/opencv.git<br />
git checkout 2.4.2<br />
Use CMake to build opencv with the following configuration:<br />
BUILD_EXAMPLES = OFF<br />
BUILD_TESTS = OFF<br />
WITH_FFMPEG = ON<br />
<br />
<br />
2. Build VXL: <br />
svn co https://vxl.svn.sourceforge.net/svnroot/vxl/trunk vxl<br />
The revision number tested is 34805 ( 2012-04-23). Later version should work (but not tested).<br />
se CMake to build opencv with the following configuration:<br />
BUILD_EXAMPLES = OFF<br />
BUILD_DOCUMENTATION = OFF<br />
<br />
<br />
3. Enable Video modules when configure ITK in CMake:<br />
Module_ITKVideoCore = ON (turn on by default)<br />
Module_ITKVideoFiltering = ON (turn on by default)<br />
Module_ITKVideoIO = ON (turn on by default)<br />
Module_ITKVideoBridgeOpenCV = ON (need to manually toggle this option ON)<br />
Module_ITKVideoBridgeVXL =ON (need to manually toggle this option ON)<br />
Then, set system library Paths for OpenCV and VXL accordingly:<br />
OpenCV_DIR = <the path where you build the OpenCV><br />
VXL_DIR = <the path where you build the VXL></div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK/Policy_and_Procedures_for_Adding_Remote_Modules&diff=53893ITK/Policy and Procedures for Adding Remote Modules2013-08-26T15:48:01Z<p>Xiaoxiao: </p>
<hr />
<div>Remote modules are downloaded at CMake configuration time into the ''Remote'' module group, i.e. into the ''Modules/Remote'' directory of the repository tree. A Remote Module can be enabled by setting the target ''Fetch_<module name>'' CMake configuration variable to ''ON''.<br />
<br />
= Purpose of Remote Modules =<br />
<br />
The new modularization resulting from the ITKv4 effort provides a new level of<br />
organization and extensibility to the toolkit. A module that follows the<br />
directory layout and has the required ITK modularization CMake content that is<br />
placed in one of the Module Groups of the repository will be automatically picked<br />
up and added to the build.<br />
<br />
While individuals or organizations can work on their own private modules and<br />
optionally make these modules publically available, the listing of Remote modules<br />
in the main ITK repository has two benefits:<br />
<br />
# Amalgation of modules prevents the need for module consumers to spend an extended effort searching for algorithm implementations.<br />
# Integration of the Remotes into the repository make it trivial to download the module and automatic fetch it in a build.<br />
<br />
Good candidates for addition to the collection can be<br />
<br />
* ITK based code that have additional third-party dependencies not bundled with the toolkit.<br />
* New algorithms or implementations seeking greater exposure and adoption.<br />
* Algorithms that hope to eventually be integrated into the toolkit.<br />
* Niche algorithms with limited application.<br />
* Modules in progress that do not yet have the test coverage and cross-platform standards required by the main toolkit.<br />
<br />
In general, the Remote Module system is medium for articles submitted in the Insight Journal to see greater adoption or transition into the toolkit.<br />
<br />
= Policy for Adding and Removing Remote Modules =<br />
<br />
A module can be added to the list of remotes if it satifies the following criteria:<br />
<br />
* There is an article in an open access journal (such as the Insight Journal) describing the theory behind and usage of the module.<br />
* There is a nightly build against ITK master on the CDash dashboard that builds and passes tests successfully.<br />
* A name and contact email exists for the dashboard build. The maintainer of the dashboard build does not necessarily need to be the original author of the Insight Journal article.<br />
<br />
At the beginning of the release candidate phase of a release, maintainers of failing module dashboard builds will be contacted. If a module's dashboard submission is still failing at the last release candidate tagging, it will be removed before the final release.<br />
<br />
Module names must be unique.<br />
<br />
At no time in the future should a module in the main repository depend on Remote module.<br />
<br />
= Procedure for Adding a Remote Module =<br />
<br />
# Publish an open access article describing the module in an online journal like the [http://insight-journal.org/ Insight Journal].<br />
# [[ITK/Git/Dashboard|Set up a nightly dashboard submission]] for the module against the master branch of ITK.<br />
# [[ITK/Git/Develop|Submit a Gerrit patch]] that adds a file named Modules/Remote/<module name>.remote.cmake. This file must have the following:<br />
## Dashboard maintainer name and email in the comments.<br />
## A call to the itk_fetch_module CMake function (documented in CMake/ITKModuleRemote.cmake) whose arguments are:<br />
### The name of the remote module; '''Note that in each <remote module name>.remote.cmake, the first argument of the function itk_fetch_module() is the name of the remote module, and it has to be consistent with the module name defined in the corresponding itk-module.cmake. To better distinguish the remote modules from the internal ITK modules, the names of the remote modules should NOT contain the "ITK" string prefix.'''<br />
### A short description of the module with the handle to the open access article.<br />
### URL's describing the location and version of the code to download.<br />
# Send a message to the [http://itk.org/ITK/help/mailing.html insight-users and insight-developers mailing lists] with the subject "New Remote Module: <module name>" and with a body that has pointers to the nightly dashboard submission and the Gerrit Change-Id.</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK/Policy_and_Procedures_for_Adding_Remote_Modules&diff=53892ITK/Policy and Procedures for Adding Remote Modules2013-08-26T15:47:10Z<p>Xiaoxiao: /* Procedure for Adding a Remote Module */</p>
<hr />
<div>Remote modules are downloaded at CMake configuration time into the ''Remote'' module group, i.e. into the ''Modules/Remote'' directory of the repository tree. A Remote Module can be enabled by setting the target ''Fetch_<module name>'' CMake configuration variable to ''ON''.<br />
<br />
== Purpose of Remote Modules ==<br />
<br />
The new modularization resulting from the ITKv4 effort provides a new level of<br />
organization and extensibility to the toolkit. A module that follows the<br />
directory layout and has the required ITK modularization CMake content that is<br />
placed in one of the Module Groups of the repository will be automatically picked<br />
up and added to the build.<br />
<br />
While individuals or organizations can work on their own private modules and<br />
optionally make these modules publically available, the listing of Remote modules<br />
in the main ITK repository has two benefits:<br />
<br />
# Amalgation of modules prevents the need for module consumers to spend an extended effort searching for algorithm implementations.<br />
# Integration of the Remotes into the repository make it trivial to download the module and automatic fetch it in a build.<br />
<br />
Good candidates for addition to the collection can be<br />
<br />
* ITK based code that have additional third-party dependencies not bundled with the toolkit.<br />
* New algorithms or implementations seeking greater exposure and adoption.<br />
* Algorithms that hope to eventually be integrated into the toolkit.<br />
* Niche algorithms with limited application.<br />
* Modules in progress that do not yet have the test coverage and cross-platform standards required by the main toolkit.<br />
<br />
In general, the Remote Module system is medium for articles submitted in the Insight Journal to see greater adoption or transition into the toolkit.<br />
<br />
== Policy for Adding and Removing Remote Modules ==<br />
<br />
A module can be added to the list of remotes if it satifies the following criteria:<br />
<br />
* There is an article in an open access journal (such as the Insight Journal) describing the theory behind and usage of the module.<br />
* There is a nightly build against ITK master on the CDash dashboard that builds and passes tests successfully.<br />
* A name and contact email exists for the dashboard build. The maintainer of the dashboard build does not necessarily need to be the original author of the Insight Journal article.<br />
<br />
At the beginning of the release candidate phase of a release, maintainers of failing module dashboard builds will be contacted. If a module's dashboard submission is still failing at the last release candidate tagging, it will be removed before the final release.<br />
<br />
Module names must be unique.<br />
<br />
At no time in the future should a module in the main repository depend on Remote module.<br />
<br />
== Procedure for Adding a Remote Module ==<br />
<br />
# Publish an open access article describing the module in an online journal like the [http://insight-journal.org/ Insight Journal].<br />
# [[ITK/Git/Dashboard|Set up a nightly dashboard submission]] for the module against the master branch of ITK.<br />
# [[ITK/Git/Develop|Submit a Gerrit patch]] that adds a file named Modules/Remote/<module name>.remote.cmake. This file must have the following:<br />
## Dashboard maintainer name and email in the comments.<br />
## A call to the itk_fetch_module CMake function (documented in CMake/ITKModuleRemote.cmake) whose arguments are:<br />
### The name of the remote module; '''Note that in each <remote module name>.remote.cmake, the first argument of the function itk_fetch_module() is the name of the remote module, and it has to be consistent with the module name defined in the corresponding itk-module.cmake. To better distinguish the remote modules from the internal ITK modules, the names of the remote modules should NOT contain the "ITK" string prefix.'''<br />
### A short description of the module with the handle to the open access article.<br />
### URL's describing the location and version of the code to download.<br />
# Send a message to the [http://itk.org/ITK/help/mailing.html insight-users and insight-developers mailing lists] with the subject "New Remote Module: <module name>" and with a body that has pointers to the nightly dashboard submission and the Gerrit Change-Id.</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK/Policy_and_Procedures_for_Adding_Remote_Modules&diff=53891ITK/Policy and Procedures for Adding Remote Modules2013-08-26T15:45:36Z<p>Xiaoxiao: /* Procedure for Adding a Remote Module */</p>
<hr />
<div>Remote modules are downloaded at CMake configuration time into the ''Remote'' module group, i.e. into the ''Modules/Remote'' directory of the repository tree. A Remote Module can be enabled by setting the target ''Fetch_<module name>'' CMake configuration variable to ''ON''.<br />
<br />
== Purpose of Remote Modules ==<br />
<br />
The new modularization resulting from the ITKv4 effort provides a new level of<br />
organization and extensibility to the toolkit. A module that follows the<br />
directory layout and has the required ITK modularization CMake content that is<br />
placed in one of the Module Groups of the repository will be automatically picked<br />
up and added to the build.<br />
<br />
While individuals or organizations can work on their own private modules and<br />
optionally make these modules publically available, the listing of Remote modules<br />
in the main ITK repository has two benefits:<br />
<br />
# Amalgation of modules prevents the need for module consumers to spend an extended effort searching for algorithm implementations.<br />
# Integration of the Remotes into the repository make it trivial to download the module and automatic fetch it in a build.<br />
<br />
Good candidates for addition to the collection can be<br />
<br />
* ITK based code that have additional third-party dependencies not bundled with the toolkit.<br />
* New algorithms or implementations seeking greater exposure and adoption.<br />
* Algorithms that hope to eventually be integrated into the toolkit.<br />
* Niche algorithms with limited application.<br />
* Modules in progress that do not yet have the test coverage and cross-platform standards required by the main toolkit.<br />
<br />
In general, the Remote Module system is medium for articles submitted in the Insight Journal to see greater adoption or transition into the toolkit.<br />
<br />
== Policy for Adding and Removing Remote Modules ==<br />
<br />
A module can be added to the list of remotes if it satifies the following criteria:<br />
<br />
* There is an article in an open access journal (such as the Insight Journal) describing the theory behind and usage of the module.<br />
* There is a nightly build against ITK master on the CDash dashboard that builds and passes tests successfully.<br />
* A name and contact email exists for the dashboard build. The maintainer of the dashboard build does not necessarily need to be the original author of the Insight Journal article.<br />
<br />
At the beginning of the release candidate phase of a release, maintainers of failing module dashboard builds will be contacted. If a module's dashboard submission is still failing at the last release candidate tagging, it will be removed before the final release.<br />
<br />
Module names must be unique.<br />
<br />
At no time in the future should a module in the main repository depend on Remote module.<br />
<br />
== Procedure for Adding a Remote Module ==<br />
<br />
# Publish an open access article describing the module in an online journal like the [http://insight-journal.org/ Insight Journal].<br />
# [[ITK/Git/Dashboard|Set up a nightly dashboard submission]] for the module against the master branch of ITK.<br />
# [[ITK/Git/Develop|Submit a Gerrit patch]] that adds a file named Modules/Remote/<module name>.remote.cmake. This file must have the following:<br />
## Dashboard maintainer name and email in the comments.<br />
## A call to the itk_fetch_module CMake function (documented in CMake/ITKModuleRemote.cmake) whose arguments are:<br />
### The name of the remote module; '''Note that in each <remote module name>.remote.cmake, the first argument of the function itk_fetch_module() is the name of the remote module, and it has to be consistent with the module name definition in itk-module.cmake. To better distinguish the remote modules from the internal ITK modules, the names of the remote modules should not contain the "ITK" string prefix.'''<br />
### A short description of the module with the handle to the open access article.<br />
### URL's describing the location and version of the code to download.<br />
# Send a message to the [http://itk.org/ITK/help/mailing.html insight-users and insight-developers mailing lists] with the subject "New Remote Module: <module name>" and with a body that has pointers to the nightly dashboard submission and the Gerrit Change-Id.</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK/Policy_and_Procedures_for_Adding_Remote_Modules&diff=53890ITK/Policy and Procedures for Adding Remote Modules2013-08-26T15:45:12Z<p>Xiaoxiao: /* Procedure for Adding a Remote Module */</p>
<hr />
<div>Remote modules are downloaded at CMake configuration time into the ''Remote'' module group, i.e. into the ''Modules/Remote'' directory of the repository tree. A Remote Module can be enabled by setting the target ''Fetch_<module name>'' CMake configuration variable to ''ON''.<br />
<br />
== Purpose of Remote Modules ==<br />
<br />
The new modularization resulting from the ITKv4 effort provides a new level of<br />
organization and extensibility to the toolkit. A module that follows the<br />
directory layout and has the required ITK modularization CMake content that is<br />
placed in one of the Module Groups of the repository will be automatically picked<br />
up and added to the build.<br />
<br />
While individuals or organizations can work on their own private modules and<br />
optionally make these modules publically available, the listing of Remote modules<br />
in the main ITK repository has two benefits:<br />
<br />
# Amalgation of modules prevents the need for module consumers to spend an extended effort searching for algorithm implementations.<br />
# Integration of the Remotes into the repository make it trivial to download the module and automatic fetch it in a build.<br />
<br />
Good candidates for addition to the collection can be<br />
<br />
* ITK based code that have additional third-party dependencies not bundled with the toolkit.<br />
* New algorithms or implementations seeking greater exposure and adoption.<br />
* Algorithms that hope to eventually be integrated into the toolkit.<br />
* Niche algorithms with limited application.<br />
* Modules in progress that do not yet have the test coverage and cross-platform standards required by the main toolkit.<br />
<br />
In general, the Remote Module system is medium for articles submitted in the Insight Journal to see greater adoption or transition into the toolkit.<br />
<br />
== Policy for Adding and Removing Remote Modules ==<br />
<br />
A module can be added to the list of remotes if it satifies the following criteria:<br />
<br />
* There is an article in an open access journal (such as the Insight Journal) describing the theory behind and usage of the module.<br />
* There is a nightly build against ITK master on the CDash dashboard that builds and passes tests successfully.<br />
* A name and contact email exists for the dashboard build. The maintainer of the dashboard build does not necessarily need to be the original author of the Insight Journal article.<br />
<br />
At the beginning of the release candidate phase of a release, maintainers of failing module dashboard builds will be contacted. If a module's dashboard submission is still failing at the last release candidate tagging, it will be removed before the final release.<br />
<br />
Module names must be unique.<br />
<br />
At no time in the future should a module in the main repository depend on Remote module.<br />
<br />
== Procedure for Adding a Remote Module ==<br />
<br />
# Publish an open access article describing the module in an online journal like the [http://insight-journal.org/ Insight Journal].<br />
# [[ITK/Git/Dashboard|Set up a nightly dashboard submission]] for the module against the master branch of ITK.<br />
# [[ITK/Git/Develop|Submit a Gerrit patch]] that adds a file named Modules/Remote/<module name>.remote.cmake. This file must have the following:<br />
## Dashboard maintainer name and email in the comments.<br />
## A call to the itk_fetch_module CMake function (documented in CMake/ITKModuleRemote.cmake) whose arguments are:<br />
### The name of the remote module; Note that in each <remote module name>.remote.cmake, the first argument of the function itk_fetch_module() is the name of the remote module, and it has to be consistent with the module name definition in itk-module.cmake. To better distinguish the remote modules from the internal ITK modules, the names of the remote modules should not contain the "ITK" string prefix.<br />
### A short description of the module with the handle to the open access article.<br />
### URL's describing the location and version of the code to download.<br />
# Send a message to the [http://itk.org/ITK/help/mailing.html insight-users and insight-developers mailing lists] with the subject "New Remote Module: <module name>" and with a body that has pointers to the nightly dashboard submission and the Gerrit Change-Id.</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK/Policy_and_Procedures_for_Adding_Remote_Modules&diff=53889ITK/Policy and Procedures for Adding Remote Modules2013-08-26T15:38:50Z<p>Xiaoxiao: /* Procedure for Adding a Remote Module */</p>
<hr />
<div>Remote modules are downloaded at CMake configuration time into the ''Remote'' module group, i.e. into the ''Modules/Remote'' directory of the repository tree. A Remote Module can be enabled by setting the target ''Fetch_<module name>'' CMake configuration variable to ''ON''.<br />
<br />
== Purpose of Remote Modules ==<br />
<br />
The new modularization resulting from the ITKv4 effort provides a new level of<br />
organization and extensibility to the toolkit. A module that follows the<br />
directory layout and has the required ITK modularization CMake content that is<br />
placed in one of the Module Groups of the repository will be automatically picked<br />
up and added to the build.<br />
<br />
While individuals or organizations can work on their own private modules and<br />
optionally make these modules publically available, the listing of Remote modules<br />
in the main ITK repository has two benefits:<br />
<br />
# Amalgation of modules prevents the need for module consumers to spend an extended effort searching for algorithm implementations.<br />
# Integration of the Remotes into the repository make it trivial to download the module and automatic fetch it in a build.<br />
<br />
Good candidates for addition to the collection can be<br />
<br />
* ITK based code that have additional third-party dependencies not bundled with the toolkit.<br />
* New algorithms or implementations seeking greater exposure and adoption.<br />
* Algorithms that hope to eventually be integrated into the toolkit.<br />
* Niche algorithms with limited application.<br />
* Modules in progress that do not yet have the test coverage and cross-platform standards required by the main toolkit.<br />
<br />
In general, the Remote Module system is medium for articles submitted in the Insight Journal to see greater adoption or transition into the toolkit.<br />
<br />
== Policy for Adding and Removing Remote Modules ==<br />
<br />
A module can be added to the list of remotes if it satifies the following criteria:<br />
<br />
* There is an article in an open access journal (such as the Insight Journal) describing the theory behind and usage of the module.<br />
* There is a nightly build against ITK master on the CDash dashboard that builds and passes tests successfully.<br />
* A name and contact email exists for the dashboard build. The maintainer of the dashboard build does not necessarily need to be the original author of the Insight Journal article.<br />
<br />
At the beginning of the release candidate phase of a release, maintainers of failing module dashboard builds will be contacted. If a module's dashboard submission is still failing at the last release candidate tagging, it will be removed before the final release.<br />
<br />
Module names must be unique.<br />
<br />
At no time in the future should a module in the main repository depend on Remote module.<br />
<br />
== Procedure for Adding a Remote Module ==<br />
<br />
# Publish an open access article describing the module in an online journal like the [http://insight-journal.org/ Insight Journal].<br />
# [[ITK/Git/Dashboard|Set up a nightly dashboard submission]] for the module against the master branch of ITK.<br />
# [[ITK/Git/Develop|Submit a Gerrit patch]] that adds a file named Modules/Remote/<module name>.remote.cmake. This file must have the following:<br />
## Dashboard maintainer name and email in the comments.<br />
## A call to the itk_fetch_module CMake function (documented in CMake/ITKModuleRemote.cmake) whose arguments are:<br />
### The name of the remote module; Note that the name should NOT contain the "ITK" prefix.<br />
### A short description of the module with the handle to the open access article.<br />
### URL's describing the location and version of the code to download.<br />
# Send a message to the [http://itk.org/ITK/help/mailing.html insight-users and insight-developers mailing lists] with the subject "New Remote Module: <module name>" and with a body that has pointers to the nightly dashboard submission and the Gerrit Change-Id.</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK_Release_4/MigrationGuideDeveloperTutorial&diff=53840ITK Release 4/MigrationGuideDeveloperTutorial2013-08-15T20:32:23Z<p>Xiaoxiao: /* 3 - Manually edit XML file */</p>
<hr />
<div>=General Steps=<br />
This tutorial provides a walkthrough of how to document changes made to the API during the ITKv4 development process. The steps of this guide only need to be followed when making an API change. The process consists of creating an XML document in the $ITK_SOURCE_DIR/Migration folder that represents the changes made to the API and including this document in the patch that gets reviewed in Gerrit. Using the automated initialization script, '''this should take roughly 10-15 minutes''' for simple changes.<br />
<br />
=Quick Version=<br />
==1 - Make the change==<br />
<pre><br />
(master)$ git checkout -b DescriptiveName<br />
(DescriptiveName)$ vim Code/Common/itkInterestingFile.h<br />
(DescriptiveName)$ ...<br />
(DescriptiveName)$ git commit -a<br />
</pre><br />
<br />
==2 - Initialize XML file==<br />
<pre><br />
(DescriptiveName)$python $ITK_SOURCE/Documentation/Migration/InitializeXMLGuide.py<br />
Please enter a unique name for the XML document<br />
>> DescriptiveName.xml<br />
</pre><br />
<br />
==3 - Manually edit XML file==<br />
<pre><br />
(DescriptiveName)$ vim Documentation/Migration/DescriptiveName.xml<br />
</pre><br />
<br />
==4 - Commit the XML file==<br />
<pre><br />
(DescriptiveName)$ git add Migration/DescriptiveName.xml<br />
(DescriptiveName)$ git commit<br />
</pre><br />
<br />
==5 - Push to gerrit==<br />
<pre><br />
(DescriptiveName)$ git gerrit-push<br />
</pre><br />
<br />
=Detailed Version=<br />
<br />
==Step 1 - Make the Change==<br />
====Start a new topic branch for the desired change====<br />
<pre><br />
$ git checkout master<br />
(master)$ git pullall<br />
(master)$ git checkout -b DescriptiveName<br />
(DescriptiveName)$<br />
</pre><br />
* This topic branch should only be used to make the desired API change (it should not combine multiple change topics)<br />
* Give the branch a descriptive name that corresponds to the nature of the API change<br />
* The topic branch name should correspond to the name for the XML document<br />
<br />
====Make the API changes locally====<br />
<pre><br />
(DescriptiveName)$ vim itkInterestingFile.h<br />
(DescriptiveName *)$<br />
</pre><br />
====Commit the changes====<br />
<pre><br />
(DescriptiveName *)$ git add itkInterestingFile.h<br />
(DescriptiveName +)$ git commit<br />
... This change takes itkInterestingFile and does such and such to it. The change was made for the following really really good reason...<br />
(DescriptiveName)$<br />
</pre><br />
* The changes must be committed prior to using the automatic XML initialization tool<br />
* Make sure to use descriptive commit messages for all commits since they will be used by the automatic tool when initializing the XML document<br />
<br />
==Step 2 - Create the XML Document==<br />
* Follow the steps in either the [[#Manual XML Document Generation|Manual Instructions]] or the [[#Automatic XML Document Generation|Automatic Instructions]] to create an XML document for the API change.<br />
* XML documents from all API changes will live in $ITK_SOURCE_DIR/Migration<br />
* Once written, commit the XML document to the local topic branch<br />
<pre><br />
(DescriptiveName *)$ git add Migration/DescriptiveName.xml<br />
(DescriptiveName +)$ git commit<br />
... DOC: Migration guide page<br />
...<br />
... Documenting such and such API change for the migration guide ...<br />
(DescriptiveName)$<br />
</pre><br />
<br />
==Step 3 - Review in Gerrit==<br />
* Once the XML document has been committed, push the topic branch to Gerrit for review<br />
<pre><br />
(DescriptiveName)$ git gerrit-push<br />
</pre><br />
* For more details on the pushing a topic to Gerrit, see the [[ITK/Gerrit/Primer|Gerrit Primer]]<br />
* Make any changes desired by the members of the review committee<br />
<br />
==Step 4 - Finalize the Change==<br />
* Once the patch, including the Migration Guide XML document, has been accepted by the reivew committee, the topic is ready to be merged into ''master''<br />
* For instructions on merging to ''master'', see the bottom of the [[ITK/Gerrit/Primer#Stage changes into the ITK official repository|Gerrit Primer]]<br />
<br />
=Manual XML Document Generation=<br />
* Create a new file in $ITK_SOURCE/Migration with a unique name<br />
* The file must follow the format:<br />
<pre><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<br />
<Change><br />
<br />
...<br />
...<br />
<br />
</Change><br />
<br />
</pre><br />
<br />
* The following elements must be defined inside the <Change> element in order for the change to be considered fully documented:<br />
** '''<Title>''': English title for migration guide page<br />
** '''<Author>''': Your name as the author of the change<br />
** '''<Date>''': The date the XML file was made<br />
** '''<Description>''': English description of what changes were made along with rational for making them.<br />
** '''<SampleCode>''': Code snippet either manually written or automatically harvested from the patch's changes that illustrates how to update the API from the old version to the new version. This element must contain two child elements, '''<Old>''' and '''<New>'''. As their names suggest, these two elements contain the snippets of old API code and new API code.<br />
** '''<FileList>''': A list of all files that were changed in association with the API change. File names should be specified relative to the base source directory for ITK.<br />
** '''<Gerrit-ChangeId>''': This element links the API change to the Gerrit entry used to review the change.<br />
<br />
* Additionally, the following elements '''should''' be added whenever possible:<br />
** '''<MigrationFix-Automatic>''': A rule for the user migration tool that can automatically fix errors in user code. These fixes will be simple find-and-replace changes, so anything that cannot be replaced throughout the entire project will be a manual fix. This element must contain '''<Old>''' and '''<New>''' child elements.<br />
** '''<MigrationFix-Manual confidence="high">''': A rule for the user migration tool that can not be automatcally fixed, but can be automatically identified. These rules will cause the user migration tool to flag a section of the code for revision. Most changes will fall in this category. The migration tool will simply search for the enclosed string and report that a problem may exist on the identified line. As such, the tool will most likely report locations that are not, in fact, problematic.<br />
*** The '''confidence''' attribute is used to indicate the developer's confidence in the warning for this manual fix.<br />
*** confidence options are '''high''', '''medium''', and '''low'''<br />
<br />
* Finally, a '''<MigrationGuideTag>''' element can be added to specify keyword tags for the migration page<br />
<br />
=Automatic XML Document Generation=<br />
* Run the XML initialization script<br />
<pre><br />
(DescriptiveName)$ python Migration/InitializeXMLGuide.py<br />
Please enter a unique name for the XML document<br />
>> DescriptiveName.xml<br />
(DescriptiveName *)$<br />
</pre><br />
* This script will parse the git history of the topic branch and create Migration/DescriptiveName.xml<br />
* In DescriptiveName.xml, the following elements must be manually edited:<br />
====<Description>====<br />
* The initialized field will look like:<br />
<pre><br />
<Description><br />
---- 839cfecfe678bb94836d94e85ecad87a82e9406e ----<br />
FIX: Fixed the API problem XXX<br />
<br />
This is a nice full description of what was changed in this<br />
commit and why.<br />
<br />
---- eba124efeb163af974b9bf3b921b5724b1ece5d6 ----<br />
FIX: Started fixing API problem XXX<br />
<br />
This is also a nice description.<br />
</Description><br />
</pre><br />
* The end goal should look something like<br />
<pre><br />
<Description><br />
This is a nice concise description of what happened over the<br />
course of all the commits for this topic. It takes advantage<br />
of all the information from the commit messages from the branch.<br />
</Description><br />
</pre><br />
* The goal behind populating the <Description> element with information from the commit messages is to ensure that the information from good git commits doesn't need to be duplicated<br />
* Much of the initial body of this element will need to be removed (especially the commit hashes) since this will be what a user sees on the migration page<br />
<br />
====<SampleCode>====<br />
* This element will be populated by all the changes that have been made in files from the Examples and Testing directories<br />
* The initial contents will look like:<br />
<pre><br />
<SampleCode><br />
<Old><br />
---- InterestingExampleFile.cxx ----<br />
#include "OldName.h"<br />
<br />
---- InterestingTestingFile.cxx ----<br />
filter->OldMethodName();<br />
</Old><br />
<br />
<New><br />
---- InterestingExampleFile.cxx ----<br />
#include "NewName.h"<br />
<br />
---- InterestingTestingFile.cxx ----<br />
filter->NewMethodName();<br />
</New><br />
<br />
</SampleCode><br />
</pre><br />
* The final version should look something like<br />
<pre><br />
<SampleCode><br />
<Old><br />
#include "OldName.h"<br />
...<br />
typedef InterestingFilter FilterType;<br />
FilterType::Pointer filter = FilterType::New();<br />
filter->OldMethodName();<br />
</Old><br />
<br />
<New><br />
#include "NewName.h"<br />
...<br />
typedef InterestingFilter FilterType;<br />
FilterType::Pointer filter = FilterType::New();<br />
filter->NewMethodName();<br />
</New><br />
<br />
</SampleCode><br />
</pre><br />
* The initial contents of this file should show examples of how applications (Examples and Tests) must be fixed for the new API change<br />
* The goal of this element is to provide a concise overview of how to make these fixes, so the initial contents must be manually edited into a single example fix</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK_Release_4/MigrationGuideDeveloperTutorial&diff=53839ITK Release 4/MigrationGuideDeveloperTutorial2013-08-15T20:30:51Z<p>Xiaoxiao: /* 2 - Initialize XML file */</p>
<hr />
<div>=General Steps=<br />
This tutorial provides a walkthrough of how to document changes made to the API during the ITKv4 development process. The steps of this guide only need to be followed when making an API change. The process consists of creating an XML document in the $ITK_SOURCE_DIR/Migration folder that represents the changes made to the API and including this document in the patch that gets reviewed in Gerrit. Using the automated initialization script, '''this should take roughly 10-15 minutes''' for simple changes.<br />
<br />
=Quick Version=<br />
==1 - Make the change==<br />
<pre><br />
(master)$ git checkout -b DescriptiveName<br />
(DescriptiveName)$ vim Code/Common/itkInterestingFile.h<br />
(DescriptiveName)$ ...<br />
(DescriptiveName)$ git commit -a<br />
</pre><br />
<br />
==2 - Initialize XML file==<br />
<pre><br />
(DescriptiveName)$python $ITK_SOURCE/Documentation/Migration/InitializeXMLGuide.py<br />
Please enter a unique name for the XML document<br />
>> DescriptiveName.xml<br />
</pre><br />
<br />
==3 - Manually edit XML file==<br />
<pre><br />
(DescriptiveName)$ vim Migration/DescriptiveName.xml<br />
</pre><br />
<br />
==4 - Commit the XML file==<br />
<pre><br />
(DescriptiveName)$ git add Migration/DescriptiveName.xml<br />
(DescriptiveName)$ git commit<br />
</pre><br />
<br />
==5 - Push to gerrit==<br />
<pre><br />
(DescriptiveName)$ git gerrit-push<br />
</pre><br />
<br />
=Detailed Version=<br />
<br />
==Step 1 - Make the Change==<br />
====Start a new topic branch for the desired change====<br />
<pre><br />
$ git checkout master<br />
(master)$ git pullall<br />
(master)$ git checkout -b DescriptiveName<br />
(DescriptiveName)$<br />
</pre><br />
* This topic branch should only be used to make the desired API change (it should not combine multiple change topics)<br />
* Give the branch a descriptive name that corresponds to the nature of the API change<br />
* The topic branch name should correspond to the name for the XML document<br />
<br />
====Make the API changes locally====<br />
<pre><br />
(DescriptiveName)$ vim itkInterestingFile.h<br />
(DescriptiveName *)$<br />
</pre><br />
====Commit the changes====<br />
<pre><br />
(DescriptiveName *)$ git add itkInterestingFile.h<br />
(DescriptiveName +)$ git commit<br />
... This change takes itkInterestingFile and does such and such to it. The change was made for the following really really good reason...<br />
(DescriptiveName)$<br />
</pre><br />
* The changes must be committed prior to using the automatic XML initialization tool<br />
* Make sure to use descriptive commit messages for all commits since they will be used by the automatic tool when initializing the XML document<br />
<br />
==Step 2 - Create the XML Document==<br />
* Follow the steps in either the [[#Manual XML Document Generation|Manual Instructions]] or the [[#Automatic XML Document Generation|Automatic Instructions]] to create an XML document for the API change.<br />
* XML documents from all API changes will live in $ITK_SOURCE_DIR/Migration<br />
* Once written, commit the XML document to the local topic branch<br />
<pre><br />
(DescriptiveName *)$ git add Migration/DescriptiveName.xml<br />
(DescriptiveName +)$ git commit<br />
... DOC: Migration guide page<br />
...<br />
... Documenting such and such API change for the migration guide ...<br />
(DescriptiveName)$<br />
</pre><br />
<br />
==Step 3 - Review in Gerrit==<br />
* Once the XML document has been committed, push the topic branch to Gerrit for review<br />
<pre><br />
(DescriptiveName)$ git gerrit-push<br />
</pre><br />
* For more details on the pushing a topic to Gerrit, see the [[ITK/Gerrit/Primer|Gerrit Primer]]<br />
* Make any changes desired by the members of the review committee<br />
<br />
==Step 4 - Finalize the Change==<br />
* Once the patch, including the Migration Guide XML document, has been accepted by the reivew committee, the topic is ready to be merged into ''master''<br />
* For instructions on merging to ''master'', see the bottom of the [[ITK/Gerrit/Primer#Stage changes into the ITK official repository|Gerrit Primer]]<br />
<br />
=Manual XML Document Generation=<br />
* Create a new file in $ITK_SOURCE/Migration with a unique name<br />
* The file must follow the format:<br />
<pre><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<br />
<Change><br />
<br />
...<br />
...<br />
<br />
</Change><br />
<br />
</pre><br />
<br />
* The following elements must be defined inside the <Change> element in order for the change to be considered fully documented:<br />
** '''<Title>''': English title for migration guide page<br />
** '''<Author>''': Your name as the author of the change<br />
** '''<Date>''': The date the XML file was made<br />
** '''<Description>''': English description of what changes were made along with rational for making them.<br />
** '''<SampleCode>''': Code snippet either manually written or automatically harvested from the patch's changes that illustrates how to update the API from the old version to the new version. This element must contain two child elements, '''<Old>''' and '''<New>'''. As their names suggest, these two elements contain the snippets of old API code and new API code.<br />
** '''<FileList>''': A list of all files that were changed in association with the API change. File names should be specified relative to the base source directory for ITK.<br />
** '''<Gerrit-ChangeId>''': This element links the API change to the Gerrit entry used to review the change.<br />
<br />
* Additionally, the following elements '''should''' be added whenever possible:<br />
** '''<MigrationFix-Automatic>''': A rule for the user migration tool that can automatically fix errors in user code. These fixes will be simple find-and-replace changes, so anything that cannot be replaced throughout the entire project will be a manual fix. This element must contain '''<Old>''' and '''<New>''' child elements.<br />
** '''<MigrationFix-Manual confidence="high">''': A rule for the user migration tool that can not be automatcally fixed, but can be automatically identified. These rules will cause the user migration tool to flag a section of the code for revision. Most changes will fall in this category. The migration tool will simply search for the enclosed string and report that a problem may exist on the identified line. As such, the tool will most likely report locations that are not, in fact, problematic.<br />
*** The '''confidence''' attribute is used to indicate the developer's confidence in the warning for this manual fix.<br />
*** confidence options are '''high''', '''medium''', and '''low'''<br />
<br />
* Finally, a '''<MigrationGuideTag>''' element can be added to specify keyword tags for the migration page<br />
<br />
=Automatic XML Document Generation=<br />
* Run the XML initialization script<br />
<pre><br />
(DescriptiveName)$ python Migration/InitializeXMLGuide.py<br />
Please enter a unique name for the XML document<br />
>> DescriptiveName.xml<br />
(DescriptiveName *)$<br />
</pre><br />
* This script will parse the git history of the topic branch and create Migration/DescriptiveName.xml<br />
* In DescriptiveName.xml, the following elements must be manually edited:<br />
====<Description>====<br />
* The initialized field will look like:<br />
<pre><br />
<Description><br />
---- 839cfecfe678bb94836d94e85ecad87a82e9406e ----<br />
FIX: Fixed the API problem XXX<br />
<br />
This is a nice full description of what was changed in this<br />
commit and why.<br />
<br />
---- eba124efeb163af974b9bf3b921b5724b1ece5d6 ----<br />
FIX: Started fixing API problem XXX<br />
<br />
This is also a nice description.<br />
</Description><br />
</pre><br />
* The end goal should look something like<br />
<pre><br />
<Description><br />
This is a nice concise description of what happened over the<br />
course of all the commits for this topic. It takes advantage<br />
of all the information from the commit messages from the branch.<br />
</Description><br />
</pre><br />
* The goal behind populating the <Description> element with information from the commit messages is to ensure that the information from good git commits doesn't need to be duplicated<br />
* Much of the initial body of this element will need to be removed (especially the commit hashes) since this will be what a user sees on the migration page<br />
<br />
====<SampleCode>====<br />
* This element will be populated by all the changes that have been made in files from the Examples and Testing directories<br />
* The initial contents will look like:<br />
<pre><br />
<SampleCode><br />
<Old><br />
---- InterestingExampleFile.cxx ----<br />
#include "OldName.h"<br />
<br />
---- InterestingTestingFile.cxx ----<br />
filter->OldMethodName();<br />
</Old><br />
<br />
<New><br />
---- InterestingExampleFile.cxx ----<br />
#include "NewName.h"<br />
<br />
---- InterestingTestingFile.cxx ----<br />
filter->NewMethodName();<br />
</New><br />
<br />
</SampleCode><br />
</pre><br />
* The final version should look something like<br />
<pre><br />
<SampleCode><br />
<Old><br />
#include "OldName.h"<br />
...<br />
typedef InterestingFilter FilterType;<br />
FilterType::Pointer filter = FilterType::New();<br />
filter->OldMethodName();<br />
</Old><br />
<br />
<New><br />
#include "NewName.h"<br />
...<br />
typedef InterestingFilter FilterType;<br />
FilterType::Pointer filter = FilterType::New();<br />
filter->NewMethodName();<br />
</New><br />
<br />
</SampleCode><br />
</pre><br />
* The initial contents of this file should show examples of how applications (Examples and Tests) must be fixed for the new API change<br />
* The goal of this element is to provide a concise overview of how to make these fixes, so the initial contents must be manually edited into a single example fix</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK&diff=53517ITK2013-07-26T15:47:34Z<p>Xiaoxiao: </p>
<hr />
<div>[[File:Itk.png|center]] <br />
<br />
The National Library of Medicine '''[http://www.itk.org/ Insight Segmentation and Registration Toolkit]''' (ITK) is an open-source software system for medical image processing in two, three and more dimensions. <br />
<br />
This is the '''''ITK Wiki''''', a collaborative hypertext database of information, documentation and resources.<br />
<br />
__TOC__<br />
<br />
== Overview ==<br />
<br />
* <big><strong>[[ITK/Getting Started|Getting Started with ITK]]</strong></big><br />
* [[ITK/About|About the Insight Toolkit]]<br />
* [[ITK/FAQ|Frequently Asked Questions (FAQ)]]<br />
* [[ITK/License Information| License Information]]<br />
<br />
== Software Process ==<br />
* [http://itk.org/gitweb?p=ITK.git Git repository] : The version controlled repository.<br />
* [http://review.source.kitware.com/#/q/status:open+project:ITK,n,z Gerrit code review] : Our code review system.<br />
* [http://issues.itk.org/ Issue tracking system] : Where we report and browse bugs.<br />
* [http://www.cdash.org/CDash/index.php?project=Insight&date= Nightly build dashboard] : View the build status on a variety of platforms.<br />
* [[ITK/Development | Development]]<br />
<br />
== Resources ==<br />
<br />
* [[ITK/Documentation| Documentation]]<br />
* [[ITK/Community | Community Corner]]<br />
* [[ITK/Academic | Academic Corner]]<br />
* [[ITK/Professional | Professional Corner]]<br />
* [[ITK/Open_Science| Open Science]]<br />
* [[ITK/Other_Software| Other Software]]</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK/Getting_Started/Obtain/Windows&diff=53513ITK/Getting Started/Obtain/Windows2013-07-26T15:41:30Z<p>Xiaoxiao: </p>
<hr />
<div>You can choose between two versions of ITK:<br />
<br />
[[File:ITK_A.png]] {{font size css|400%|[[ITK/Getting_Started/Obtain/Windows/Release| Stable]]}} <br />
<br />
Things in this version will work with the highest probability :)<br />
<br />
<br />
<br />
[[File:ITK_B.png]] {{font size css|400%|[[ITK/Getting_Started/Obtain/Windows/Git| Cutting Edge]]}}<br />
<br />
There are newer and better things in this version, but all the bugs might not quite be worked out! (Don't know what "git" is? Don't worry, it's all explained inside!)</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK/Getting_Started/Obtain/Linux/Git&diff=53512ITK/Getting Started/Obtain/Linux/Git2013-07-26T15:38:51Z<p>Xiaoxiao: </p>
<hr />
<div>ITK uses Git for its version control system. If you are familiar with Git, you can find relevant information [[ITK/Source#2._Git|here]] or [[ITK/Git|here]]. If not, continue reading!<br />
<br />
To get the latest ITK source code, you must use git. If you do not have git installed, please install it from your package manager: <br />
sudo apt-get install git <br />
<br />
Once you have git installed, type this command in a terminal window:<br />
<br />
git clone git://itk.org/ITK.git<br />
<br />
This will create an ITK directory and download the latest ITK source code into that directory.<br />
<br />
''Step 1: Obtaining'' is now complete!</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK/Getting_Started&diff=53508ITK/Getting Started2013-07-26T15:34:33Z<p>Xiaoxiao: </p>
<hr />
<div>The Insight Toolkit is quite a large and complicated framework for medical image processing. While it may seem intimidating, three simple steps will get you started.<br />
<br />
[[File:ITK_0.jpg]] {{font size css|100%|[[ITK/Getting_Started/Overview | Overview]]}}<br />
<br />
[[File:ITK_1.jpg]] {{font size css|100%|[[ITK/Getting_Started/Obtain | Obtain]]}}<br />
<br />
[[File:ITK_2.jpg]] {{font size css|100%|[[ITK/Getting_Started/Build | Build]]}}<br />
<br />
[[File:ITK_3.jpg]] {{font size css|100%|[[ITK/Getting_Started/Use | Use]]}}<br />
<br />
{{ITK/Template/Footer}}</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK/Getting_Started&diff=53507ITK/Getting Started2013-07-26T15:33:59Z<p>Xiaoxiao: </p>
<hr />
<div>The Insight Toolkit is quite a large and complicated framework for medical image processing. While it may seem intimidating, three simple steps will get you started.<br />
<br />
[[File:ITK_0.jpg]] {{font size css|200%|[[ITK/Getting_Started/Overview | Overview]]}}<br />
<br />
[[File:ITK_1.jpg]] {{font size css|200%|[[ITK/Getting_Started/Obtain | Obtain]]}}<br />
<br />
[[File:ITK_2.jpg]] {{font size css|200%|[[ITK/Getting_Started/Build | Build]]}}<br />
<br />
[[File:ITK_3.jpg]] {{font size css|200%|[[ITK/Getting_Started/Use | Use]]}}<br />
<br />
{{ITK/Template/Footer}}</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK/Git/Develop&diff=52042ITK/Git/Develop2013-03-28T18:25:45Z<p>Xiaoxiao: /* Merge a Topic */</p>
<hr />
<div>__NOTOC__<br />
<br />
This page documents how to develop ITK through [http://git-scm.com Git].<br />
See our [[ITK/Git|table of contents]] for more information.<br />
<br />
<i><br />
Git is an extremely powerful version control tool that supports many different "workflows" for indivudal development and collaboration.<br />
Here we document procedures used by the ITK development community.<br />
In the interest of simplicity and brevity we do '''not''' provide an explanation of why we use this approach.<br />
Furthermore, this is '''not''' a Git tutorial.<br />
Please see our [[Git/Resources|Git resource links]] for third-party documentation, such as the [http://git-scm.com/book/ ProGit Book].<br />
</i><br />
<br />
==Setup==<br />
<br />
Before you begin, perform initial setup:<br />
<br />
{| style="width: 100%" cellspacing="0" cellpadding="0"<br />
|-<br />
|width=60%|<br />
1.<br />
Register [[ITK/Git/Account#Gerrit|Gerrit access]] and possibly [[ITK/Git/Account#Git|Git push access]].<br />
|-<br />
|<br />
2.<br />
Optionally download our [[Media:GitITKCheatSheet.pdf|one page PDF desk reference]].<br />
|-<br />
|<br />
3.<br />
Follow the [[ITK/Git/Download#Clone|download instructions]] to create a local ITK clone:<br />
|-<br />
|<br />
:<code>$ git clone git://itk.org/ITK.git</code><br />
|align="center"|<br />
[[Git/Trouble#Firewall_Blocks_Port_9418|Connection refused]]?<br />
|-<br />
|<br />
4.<br />
Run the developer setup script to prepare your ITK work tree and create Git command aliases used below:<br />
|-<br />
|<br />
:<code>$ ./Utilities/SetupForDevelopment.sh</code><br />
|align="center"|<br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/SetupForDevelopment.sh;hb=HEAD <code>SetupForDevelopment.sh</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Getting-Started-First-Time-Git-Setup Pro Git: Setup]<br />
|}<br />
<br />
==Workflow==<br />
<br />
ITK development uses a [[Git/Workflow/Topic|branchy workflow]] based on topic branches.<br />
Our collaboration workflow consists of three main steps:<br />
<br />
{| style="width: 100%" cellspacing="0" cellpadding="0"<br />
|-<br />
|width=60%|<br />
1.<br />
Local Development<br />
|-<br />
|<br />
:* [[#Update|Update]]<br />
|-<br />
|<br />
:* [[#Create_a_Topic|Create a Topic]]<br />
|-<br />
|<br />
2.<br />
Code Review<br />
|-<br />
|<br />
:* [[#Share_a_Topic|Share a Topic]] (requires [[ITK/Git/Account#Gerrit|Gerrit access]])<br />
|align="center"|<br />
[http://code.google.com/p/gerrit/ Gerrit Code Review]<br />
|-<br />
|<br />
:* [[#Revise_a_Topic|Revise a Topic]]<br />
|-<br />
|<br />
3.<br />
Integrate Changes<br />
|-<br />
|<br />
:* [[#Merge_a_Topic|Merge a Topic]] (requires [[ITK/Git/Account#Git|Git push access]])<br />
|-<br />
|<br />
:* [[#Delete_a_Topic|Delete a Topic]]<br />
|}<br />
<br />
==Update==<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Update your local '''master''' branch:<br />
|-<br />
|<br />
:<code>$ git checkout master</code><br />
:<code>$ git pullall</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
<br/><br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.pullall</code>]<br />
<br/><br />
([http://schacon.github.com/git/git-pull.html <code>pull</code>] and<br />
[http://schacon.github.com/git/git-submodule.html <code>submodule</code>] <code>update</code>)<br />
|}<br />
<br />
==Create a Topic==<br />
<br />
All new work must be committed on topic branches.<br />
Name topics like you might name functions: concise but precise.<br />
A reader should have a general idea of the feature or fix to be developed given just the branch name.<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
To start a new topic branch:<br />
|-<br />
|<br />
:<code>$ git fetch origin</code><br />
:{|<br />
|-<br />
|<br />
For new development, start the topic from <code>origin/master</code>:<br />
:<code>$ git checkout -b ''my-topic'' origin/master</code><br />
|-<br />
|<br />
For release branch fixes, start the topic from <code>origin/release</code>, and by convention use a topic name starting in "<code>release-</code>":<br />
:<code>$ git checkout -b ''my-topic'' origin/release</code><br />
|}<br />
|align="center"|<br />
[http://schacon.github.com/git/git-fetch.html <code>git help fetch</code>]<br />
<br/><br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
<br/><br />
[http://schacon.github.com/git/git-submodule.html <code>git help submodule</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging Pro Git: Basic Branching]<br />
|-<br />
|<br />
Edit files and create commits (repeat as needed):<br />
|-<br />
|<br />
:<code>$ edit ''file1'' ''file2'' ''file3''</code><br />
:''(To add data follow [[ITK/Git/Develop/Data#Add_Data|these instructions]].)''<br />
:<code>$ git add ''file1'' ''file2'' ''file3''</code><br />
:<code>$ git commit</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-add.html <code>git help add</code>]<br />
<br/><br />
[http://schacon.github.com/git/git-commit.html <code>git help commit</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Basics-Recording-Changes-to-the-Repository Pro Git: Recording Changes]<br />
|-<br />
|<br />
''(If your change modifies the "<code>Modules/ThirdParty/KWSys/src/KWSys</code>" directory please contribute directly to [[KWSys/Git|KWSys]] instead.)''<br />
|}<br />
<br />
==Share a Topic==<br />
<br />
When a topic is ready for review and possible inclusion, share it by pushing to Gerrit.<br />
Be sure you have registered for [[ITK/Git/Account#Gerrit|Gerrit access]].<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Checkout the topic if it is not your current branch:<br />
|-<br />
|<br />
:<code>$ git checkout ''my-topic''</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
|-<br />
|<br />
Check what commits will be pushed to Gerrit for review:<br />
|-<br />
|<br />
:<code>$ git prepush</code><br />
or if you started the topic from the release branch:<br />
:<code>$ git push gerrit HEAD:refs/for/release/''my-topic'' </code> <br />
|align="center"|<br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.prepush</code>]<br />
<br/><br />
([http://schacon.github.com/git/git-log.html <code>log</code>] <code>origin/master..</code>)<br />
|-<br />
|<br />
Push commits in your topic branch for review by the community:<br />
|-<br />
|<br />
:<code>$ git gerrit-push</code><br />
:''(If the topic adds data see [[ITK/Git/Develop/Data#Push|this note]].)''<br />
|align="center"|<br />
[[ITK/Git/Account#Firewall_blocks_SSH_traffic|Connection refused]]?<br />
<br/><br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.gerrit-push</code>]<br />
<br/><br />
([http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/Git/git-gerrit-push;hb=HEAD <code>Utilities/Git/git-gerrit-push</code>])<br />
|}<br />
Find your change in the [http://review.source.kitware.com/p/ITK ITK Gerrit] instance and add [[ITK/Gerrit/Reviewers|reviewers]].<br />
<br />
==Revise a Topic==<br />
<br />
If a topic is approved during Gerrit review, skip to the [[#Merge_a_Topic|next step]].<br />
Otherwise, revise the topic and push it back to Gerrit for another review.<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Checkout the topic if it is not your current branch:<br />
|-<br />
|<br />
:<code>$ git checkout ''my-topic''</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
|-<br />
|<br />
To revise the most recent commit on the topic edit files and add changes normally and then amend the commit:<br />
|-<br />
|<br />
:<code>$ git commit --amend</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-commit.html <code>git help commit</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Tools-Rewriting-History#Changing-the-Last-Commit Pro Git: Changing the Last Commit]<br />
|-<br />
|<br />
To revise commits further back on the topic, say the <code>3</code>rd commit back:<br />
|-<br />
|<br />
:<code>$ git rebase -i HEAD~3</code><br />
''(Substitute the correct number of commits back, as low as ''<code>1</code>''.)''<br />
<br />
Follow Git's interactive instructions.<br />
Preserve the <code>Change-Id:</code> line at the bottom of each commit message.<br />
|align="center"|<br />
[http://schacon.github.com/git/git-rebase.html <code>git help rebase</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Tools-Rewriting-History#Changing-Multiple-Commit-Messages Pro Git: Changing Multiple Commits]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Branching-Rebasing Pro Git: Rebasing]<br />
|-<br />
|<br />
Return to the [[#Share_a_Topic|previous step]] to share the revised topic.<br />
|}<br />
<br />
==Merge a Topic==<br />
'''Only authorized developers with [[ITK/Git/Account#Git|Git push access]] to <code>itk.org</code> may perform this step.'''<br />
<br />
After a feature topic has been reviewed and approved in Gerrit, merge it into the upstream repository.<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Checkout the topic if it is not your current branch:<br />
|-<br />
|<br />
:<code>$ git checkout ''my-topic''</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
|-<br />
|<br />
Merge the topic, which is originally forked off the master branch, to master branch:<br />
|-<br />
|<br />
:<code>$ git gerrit-merge</code><br />
<br />
:''(If the merge conflicts follow the printed instructions to resolve them.)''<br />
|align="center"|<br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.gerrit-merge</code>]<br />
<br/><br />
([http://schacon.github.com/git/git-push.html <code>push</code>] to [[Git/Workflow/Stage|topic stage]] and<br />
<br/><br />
<code>stage ITK merge ''my-topic''</code>)<br />
<br/><br />
[[Git/Workflow/Topic/Conflicts#Branch-to-Topic|Branch-to-Topic Conflict Resolution]]<br />
|}<br />
<br />
For bug fixes that are ready to be included in the next release, please email the release manager<br />
Matt Mccormick([[matt.mccormick@kitware.com)]] for assistance.<br />
<br />
Here are the recommended steps to merge a topic to both release and master branches, assuming the topic<br />
branch is forked off the release branch:<br />
:<code>$ git checkout release</code><br />
:<code>$ git merge --no-ff ''my-topic''</code><br />
:<code>$ git push origin release</code><br />
and do:<br />
:<code>$ git checkout master</code><br />
:<code>$ git merge --no-ff release</code><br />
:<code>$ git push origin master</code><br />
to merge the release branch back to master.<br />
<br />
==Delete a Topic==<br />
<br />
After a topic has been merged upstream, delete your local branch for the topic.<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Checkout and update the '''master''' branch:<br />
|-<br />
|<br />
:<code>$ git checkout master</code><br />
:<code>$ git pullall</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
<br/><br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.pullall</code>]<br />
<br/><br />
([http://schacon.github.com/git/git-pull.html <code>pull</code>] and<br />
[http://schacon.github.com/git/git-submodule.html <code>submodule</code>] <code>update</code>)<br />
|-<br />
|<br />
Delete the local topic branch:<br />
|-<br />
|<br />
:<code>$ git branch -d ''my-topic''</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-branch.html <code>git help branch</code>]<br />
|-<br />
|<br />
The <code>branch -d</code> command works only when the topic branch has been correctly merged.<br />
Use <code>-D</code> instead of <code>-d</code> to force the deletion of an unmerged topic branch<br />
(warning - you could lose commits).<br />
|}</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK/Git/Develop&diff=52041ITK/Git/Develop2013-03-28T18:24:54Z<p>Xiaoxiao: /* Merge a Topic */</p>
<hr />
<div>__NOTOC__<br />
<br />
This page documents how to develop ITK through [http://git-scm.com Git].<br />
See our [[ITK/Git|table of contents]] for more information.<br />
<br />
<i><br />
Git is an extremely powerful version control tool that supports many different "workflows" for indivudal development and collaboration.<br />
Here we document procedures used by the ITK development community.<br />
In the interest of simplicity and brevity we do '''not''' provide an explanation of why we use this approach.<br />
Furthermore, this is '''not''' a Git tutorial.<br />
Please see our [[Git/Resources|Git resource links]] for third-party documentation, such as the [http://git-scm.com/book/ ProGit Book].<br />
</i><br />
<br />
==Setup==<br />
<br />
Before you begin, perform initial setup:<br />
<br />
{| style="width: 100%" cellspacing="0" cellpadding="0"<br />
|-<br />
|width=60%|<br />
1.<br />
Register [[ITK/Git/Account#Gerrit|Gerrit access]] and possibly [[ITK/Git/Account#Git|Git push access]].<br />
|-<br />
|<br />
2.<br />
Optionally download our [[Media:GitITKCheatSheet.pdf|one page PDF desk reference]].<br />
|-<br />
|<br />
3.<br />
Follow the [[ITK/Git/Download#Clone|download instructions]] to create a local ITK clone:<br />
|-<br />
|<br />
:<code>$ git clone git://itk.org/ITK.git</code><br />
|align="center"|<br />
[[Git/Trouble#Firewall_Blocks_Port_9418|Connection refused]]?<br />
|-<br />
|<br />
4.<br />
Run the developer setup script to prepare your ITK work tree and create Git command aliases used below:<br />
|-<br />
|<br />
:<code>$ ./Utilities/SetupForDevelopment.sh</code><br />
|align="center"|<br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/SetupForDevelopment.sh;hb=HEAD <code>SetupForDevelopment.sh</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Getting-Started-First-Time-Git-Setup Pro Git: Setup]<br />
|}<br />
<br />
==Workflow==<br />
<br />
ITK development uses a [[Git/Workflow/Topic|branchy workflow]] based on topic branches.<br />
Our collaboration workflow consists of three main steps:<br />
<br />
{| style="width: 100%" cellspacing="0" cellpadding="0"<br />
|-<br />
|width=60%|<br />
1.<br />
Local Development<br />
|-<br />
|<br />
:* [[#Update|Update]]<br />
|-<br />
|<br />
:* [[#Create_a_Topic|Create a Topic]]<br />
|-<br />
|<br />
2.<br />
Code Review<br />
|-<br />
|<br />
:* [[#Share_a_Topic|Share a Topic]] (requires [[ITK/Git/Account#Gerrit|Gerrit access]])<br />
|align="center"|<br />
[http://code.google.com/p/gerrit/ Gerrit Code Review]<br />
|-<br />
|<br />
:* [[#Revise_a_Topic|Revise a Topic]]<br />
|-<br />
|<br />
3.<br />
Integrate Changes<br />
|-<br />
|<br />
:* [[#Merge_a_Topic|Merge a Topic]] (requires [[ITK/Git/Account#Git|Git push access]])<br />
|-<br />
|<br />
:* [[#Delete_a_Topic|Delete a Topic]]<br />
|}<br />
<br />
==Update==<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Update your local '''master''' branch:<br />
|-<br />
|<br />
:<code>$ git checkout master</code><br />
:<code>$ git pullall</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
<br/><br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.pullall</code>]<br />
<br/><br />
([http://schacon.github.com/git/git-pull.html <code>pull</code>] and<br />
[http://schacon.github.com/git/git-submodule.html <code>submodule</code>] <code>update</code>)<br />
|}<br />
<br />
==Create a Topic==<br />
<br />
All new work must be committed on topic branches.<br />
Name topics like you might name functions: concise but precise.<br />
A reader should have a general idea of the feature or fix to be developed given just the branch name.<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
To start a new topic branch:<br />
|-<br />
|<br />
:<code>$ git fetch origin</code><br />
:{|<br />
|-<br />
|<br />
For new development, start the topic from <code>origin/master</code>:<br />
:<code>$ git checkout -b ''my-topic'' origin/master</code><br />
|-<br />
|<br />
For release branch fixes, start the topic from <code>origin/release</code>, and by convention use a topic name starting in "<code>release-</code>":<br />
:<code>$ git checkout -b ''my-topic'' origin/release</code><br />
|}<br />
|align="center"|<br />
[http://schacon.github.com/git/git-fetch.html <code>git help fetch</code>]<br />
<br/><br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
<br/><br />
[http://schacon.github.com/git/git-submodule.html <code>git help submodule</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging Pro Git: Basic Branching]<br />
|-<br />
|<br />
Edit files and create commits (repeat as needed):<br />
|-<br />
|<br />
:<code>$ edit ''file1'' ''file2'' ''file3''</code><br />
:''(To add data follow [[ITK/Git/Develop/Data#Add_Data|these instructions]].)''<br />
:<code>$ git add ''file1'' ''file2'' ''file3''</code><br />
:<code>$ git commit</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-add.html <code>git help add</code>]<br />
<br/><br />
[http://schacon.github.com/git/git-commit.html <code>git help commit</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Basics-Recording-Changes-to-the-Repository Pro Git: Recording Changes]<br />
|-<br />
|<br />
''(If your change modifies the "<code>Modules/ThirdParty/KWSys/src/KWSys</code>" directory please contribute directly to [[KWSys/Git|KWSys]] instead.)''<br />
|}<br />
<br />
==Share a Topic==<br />
<br />
When a topic is ready for review and possible inclusion, share it by pushing to Gerrit.<br />
Be sure you have registered for [[ITK/Git/Account#Gerrit|Gerrit access]].<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Checkout the topic if it is not your current branch:<br />
|-<br />
|<br />
:<code>$ git checkout ''my-topic''</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
|-<br />
|<br />
Check what commits will be pushed to Gerrit for review:<br />
|-<br />
|<br />
:<code>$ git prepush</code><br />
or if you started the topic from the release branch:<br />
:<code>$ git push gerrit HEAD:refs/for/release/''my-topic'' </code> <br />
|align="center"|<br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.prepush</code>]<br />
<br/><br />
([http://schacon.github.com/git/git-log.html <code>log</code>] <code>origin/master..</code>)<br />
|-<br />
|<br />
Push commits in your topic branch for review by the community:<br />
|-<br />
|<br />
:<code>$ git gerrit-push</code><br />
:''(If the topic adds data see [[ITK/Git/Develop/Data#Push|this note]].)''<br />
|align="center"|<br />
[[ITK/Git/Account#Firewall_blocks_SSH_traffic|Connection refused]]?<br />
<br/><br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.gerrit-push</code>]<br />
<br/><br />
([http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/Git/git-gerrit-push;hb=HEAD <code>Utilities/Git/git-gerrit-push</code>])<br />
|}<br />
Find your change in the [http://review.source.kitware.com/p/ITK ITK Gerrit] instance and add [[ITK/Gerrit/Reviewers|reviewers]].<br />
<br />
==Revise a Topic==<br />
<br />
If a topic is approved during Gerrit review, skip to the [[#Merge_a_Topic|next step]].<br />
Otherwise, revise the topic and push it back to Gerrit for another review.<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Checkout the topic if it is not your current branch:<br />
|-<br />
|<br />
:<code>$ git checkout ''my-topic''</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
|-<br />
|<br />
To revise the most recent commit on the topic edit files and add changes normally and then amend the commit:<br />
|-<br />
|<br />
:<code>$ git commit --amend</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-commit.html <code>git help commit</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Tools-Rewriting-History#Changing-the-Last-Commit Pro Git: Changing the Last Commit]<br />
|-<br />
|<br />
To revise commits further back on the topic, say the <code>3</code>rd commit back:<br />
|-<br />
|<br />
:<code>$ git rebase -i HEAD~3</code><br />
''(Substitute the correct number of commits back, as low as ''<code>1</code>''.)''<br />
<br />
Follow Git's interactive instructions.<br />
Preserve the <code>Change-Id:</code> line at the bottom of each commit message.<br />
|align="center"|<br />
[http://schacon.github.com/git/git-rebase.html <code>git help rebase</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Tools-Rewriting-History#Changing-Multiple-Commit-Messages Pro Git: Changing Multiple Commits]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Branching-Rebasing Pro Git: Rebasing]<br />
|-<br />
|<br />
Return to the [[#Share_a_Topic|previous step]] to share the revised topic.<br />
|}<br />
<br />
==Merge a Topic==<br />
'''Only authorized developers with [[ITK/Git/Account#Git|Git push access]] to <code>itk.org</code> may perform this step.'''<br />
<br />
After a feature topic has been reviewed and approved in Gerrit, merge it into the upstream repository.<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Checkout the topic if it is not your current branch:<br />
|-<br />
|<br />
:<code>$ git checkout ''my-topic''</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
|-<br />
|<br />
Merge the topic, which is originally forked off the master branch, to master branch:<br />
|-<br />
|<br />
:<code>$ git gerrit-merge</code><br />
<br />
:''(If the merge conflicts follow the printed instructions to resolve them.)''<br />
|align="center"|<br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.gerrit-merge</code>]<br />
<br/><br />
([http://schacon.github.com/git/git-push.html <code>push</code>] to [[Git/Workflow/Stage|topic stage]] and<br />
<br/><br />
<code>stage ITK merge ''my-topic''</code>)<br />
<br/><br />
[[Git/Workflow/Topic/Conflicts#Branch-to-Topic|Branch-to-Topic Conflict Resolution]]<br />
|}<br />
<br />
For bug fixes that are ready to be included in the next release, please email the release manager<br />
Matt Mccormick([[matt.mccormick@kitware.com)]] for assistance.<br />
<br />
Here are the recommended steps to merge a topic to both release and master branches, assuming the topic<br />
branch is forked off the release branch:<br />
|-<br />
|<br />
:<code>$ git checkout release</code><br />
:<code>$ git merge --no-ff ''my-topic''</code><br />
:<code>$ git push origin release</code><br />
and do:<br />
|-<br />
|<br />
:<code>$ git checkout master</code><br />
:<code>$ git merge --no-ff release</code><br />
:<code>$ git push origin master</code><br />
to merge the release branch back to master.<br />
<br />
==Delete a Topic==<br />
<br />
After a topic has been merged upstream, delete your local branch for the topic.<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Checkout and update the '''master''' branch:<br />
|-<br />
|<br />
:<code>$ git checkout master</code><br />
:<code>$ git pullall</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
<br/><br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.pullall</code>]<br />
<br/><br />
([http://schacon.github.com/git/git-pull.html <code>pull</code>] and<br />
[http://schacon.github.com/git/git-submodule.html <code>submodule</code>] <code>update</code>)<br />
|-<br />
|<br />
Delete the local topic branch:<br />
|-<br />
|<br />
:<code>$ git branch -d ''my-topic''</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-branch.html <code>git help branch</code>]<br />
|-<br />
|<br />
The <code>branch -d</code> command works only when the topic branch has been correctly merged.<br />
Use <code>-D</code> instead of <code>-d</code> to force the deletion of an unmerged topic branch<br />
(warning - you could lose commits).<br />
|}</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK/Git/Develop&diff=52040ITK/Git/Develop2013-03-28T18:22:54Z<p>Xiaoxiao: /* Merge a Topic */</p>
<hr />
<div>__NOTOC__<br />
<br />
This page documents how to develop ITK through [http://git-scm.com Git].<br />
See our [[ITK/Git|table of contents]] for more information.<br />
<br />
<i><br />
Git is an extremely powerful version control tool that supports many different "workflows" for indivudal development and collaboration.<br />
Here we document procedures used by the ITK development community.<br />
In the interest of simplicity and brevity we do '''not''' provide an explanation of why we use this approach.<br />
Furthermore, this is '''not''' a Git tutorial.<br />
Please see our [[Git/Resources|Git resource links]] for third-party documentation, such as the [http://git-scm.com/book/ ProGit Book].<br />
</i><br />
<br />
==Setup==<br />
<br />
Before you begin, perform initial setup:<br />
<br />
{| style="width: 100%" cellspacing="0" cellpadding="0"<br />
|-<br />
|width=60%|<br />
1.<br />
Register [[ITK/Git/Account#Gerrit|Gerrit access]] and possibly [[ITK/Git/Account#Git|Git push access]].<br />
|-<br />
|<br />
2.<br />
Optionally download our [[Media:GitITKCheatSheet.pdf|one page PDF desk reference]].<br />
|-<br />
|<br />
3.<br />
Follow the [[ITK/Git/Download#Clone|download instructions]] to create a local ITK clone:<br />
|-<br />
|<br />
:<code>$ git clone git://itk.org/ITK.git</code><br />
|align="center"|<br />
[[Git/Trouble#Firewall_Blocks_Port_9418|Connection refused]]?<br />
|-<br />
|<br />
4.<br />
Run the developer setup script to prepare your ITK work tree and create Git command aliases used below:<br />
|-<br />
|<br />
:<code>$ ./Utilities/SetupForDevelopment.sh</code><br />
|align="center"|<br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/SetupForDevelopment.sh;hb=HEAD <code>SetupForDevelopment.sh</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Getting-Started-First-Time-Git-Setup Pro Git: Setup]<br />
|}<br />
<br />
==Workflow==<br />
<br />
ITK development uses a [[Git/Workflow/Topic|branchy workflow]] based on topic branches.<br />
Our collaboration workflow consists of three main steps:<br />
<br />
{| style="width: 100%" cellspacing="0" cellpadding="0"<br />
|-<br />
|width=60%|<br />
1.<br />
Local Development<br />
|-<br />
|<br />
:* [[#Update|Update]]<br />
|-<br />
|<br />
:* [[#Create_a_Topic|Create a Topic]]<br />
|-<br />
|<br />
2.<br />
Code Review<br />
|-<br />
|<br />
:* [[#Share_a_Topic|Share a Topic]] (requires [[ITK/Git/Account#Gerrit|Gerrit access]])<br />
|align="center"|<br />
[http://code.google.com/p/gerrit/ Gerrit Code Review]<br />
|-<br />
|<br />
:* [[#Revise_a_Topic|Revise a Topic]]<br />
|-<br />
|<br />
3.<br />
Integrate Changes<br />
|-<br />
|<br />
:* [[#Merge_a_Topic|Merge a Topic]] (requires [[ITK/Git/Account#Git|Git push access]])<br />
|-<br />
|<br />
:* [[#Delete_a_Topic|Delete a Topic]]<br />
|}<br />
<br />
==Update==<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Update your local '''master''' branch:<br />
|-<br />
|<br />
:<code>$ git checkout master</code><br />
:<code>$ git pullall</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
<br/><br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.pullall</code>]<br />
<br/><br />
([http://schacon.github.com/git/git-pull.html <code>pull</code>] and<br />
[http://schacon.github.com/git/git-submodule.html <code>submodule</code>] <code>update</code>)<br />
|}<br />
<br />
==Create a Topic==<br />
<br />
All new work must be committed on topic branches.<br />
Name topics like you might name functions: concise but precise.<br />
A reader should have a general idea of the feature or fix to be developed given just the branch name.<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
To start a new topic branch:<br />
|-<br />
|<br />
:<code>$ git fetch origin</code><br />
:{|<br />
|-<br />
|<br />
For new development, start the topic from <code>origin/master</code>:<br />
:<code>$ git checkout -b ''my-topic'' origin/master</code><br />
|-<br />
|<br />
For release branch fixes, start the topic from <code>origin/release</code>, and by convention use a topic name starting in "<code>release-</code>":<br />
:<code>$ git checkout -b ''my-topic'' origin/release</code><br />
|}<br />
|align="center"|<br />
[http://schacon.github.com/git/git-fetch.html <code>git help fetch</code>]<br />
<br/><br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
<br/><br />
[http://schacon.github.com/git/git-submodule.html <code>git help submodule</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging Pro Git: Basic Branching]<br />
|-<br />
|<br />
Edit files and create commits (repeat as needed):<br />
|-<br />
|<br />
:<code>$ edit ''file1'' ''file2'' ''file3''</code><br />
:''(To add data follow [[ITK/Git/Develop/Data#Add_Data|these instructions]].)''<br />
:<code>$ git add ''file1'' ''file2'' ''file3''</code><br />
:<code>$ git commit</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-add.html <code>git help add</code>]<br />
<br/><br />
[http://schacon.github.com/git/git-commit.html <code>git help commit</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Basics-Recording-Changes-to-the-Repository Pro Git: Recording Changes]<br />
|-<br />
|<br />
''(If your change modifies the "<code>Modules/ThirdParty/KWSys/src/KWSys</code>" directory please contribute directly to [[KWSys/Git|KWSys]] instead.)''<br />
|}<br />
<br />
==Share a Topic==<br />
<br />
When a topic is ready for review and possible inclusion, share it by pushing to Gerrit.<br />
Be sure you have registered for [[ITK/Git/Account#Gerrit|Gerrit access]].<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Checkout the topic if it is not your current branch:<br />
|-<br />
|<br />
:<code>$ git checkout ''my-topic''</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
|-<br />
|<br />
Check what commits will be pushed to Gerrit for review:<br />
|-<br />
|<br />
:<code>$ git prepush</code><br />
or if you started the topic from the release branch:<br />
:<code>$ git push gerrit HEAD:refs/for/release/''my-topic'' </code> <br />
|align="center"|<br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.prepush</code>]<br />
<br/><br />
([http://schacon.github.com/git/git-log.html <code>log</code>] <code>origin/master..</code>)<br />
|-<br />
|<br />
Push commits in your topic branch for review by the community:<br />
|-<br />
|<br />
:<code>$ git gerrit-push</code><br />
:''(If the topic adds data see [[ITK/Git/Develop/Data#Push|this note]].)''<br />
|align="center"|<br />
[[ITK/Git/Account#Firewall_blocks_SSH_traffic|Connection refused]]?<br />
<br/><br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.gerrit-push</code>]<br />
<br/><br />
([http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/Git/git-gerrit-push;hb=HEAD <code>Utilities/Git/git-gerrit-push</code>])<br />
|}<br />
Find your change in the [http://review.source.kitware.com/p/ITK ITK Gerrit] instance and add [[ITK/Gerrit/Reviewers|reviewers]].<br />
<br />
==Revise a Topic==<br />
<br />
If a topic is approved during Gerrit review, skip to the [[#Merge_a_Topic|next step]].<br />
Otherwise, revise the topic and push it back to Gerrit for another review.<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Checkout the topic if it is not your current branch:<br />
|-<br />
|<br />
:<code>$ git checkout ''my-topic''</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
|-<br />
|<br />
To revise the most recent commit on the topic edit files and add changes normally and then amend the commit:<br />
|-<br />
|<br />
:<code>$ git commit --amend</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-commit.html <code>git help commit</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Tools-Rewriting-History#Changing-the-Last-Commit Pro Git: Changing the Last Commit]<br />
|-<br />
|<br />
To revise commits further back on the topic, say the <code>3</code>rd commit back:<br />
|-<br />
|<br />
:<code>$ git rebase -i HEAD~3</code><br />
''(Substitute the correct number of commits back, as low as ''<code>1</code>''.)''<br />
<br />
Follow Git's interactive instructions.<br />
Preserve the <code>Change-Id:</code> line at the bottom of each commit message.<br />
|align="center"|<br />
[http://schacon.github.com/git/git-rebase.html <code>git help rebase</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Tools-Rewriting-History#Changing-Multiple-Commit-Messages Pro Git: Changing Multiple Commits]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Branching-Rebasing Pro Git: Rebasing]<br />
|-<br />
|<br />
Return to the [[#Share_a_Topic|previous step]] to share the revised topic.<br />
|}<br />
<br />
==Merge a Topic==<br />
'''Only authorized developers with [[ITK/Git/Account#Git|Git push access]] to <code>itk.org</code> may perform this step.'''<br />
<br />
After a feature topic has been reviewed and approved in Gerrit, merge it into the upstream repository.<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Checkout the topic if it is not your current branch:<br />
|-<br />
|<br />
:<code>$ git checkout ''my-topic''</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
|-<br />
|<br />
Merge the topic, which is originally forked off the master branch, to master branch:<br />
|-<br />
|<br />
:<code>$ git gerrit-merge</code><br />
<br />
For bug fixes that are ready to be included in the next release, please email the release manager<br />
Matt Mccormick([[matt.mccormick@kitware.com)]] for assistance.<br />
Here are the recommended steps to merge a topic to both release and master branches, assuming the topic<br />
branch is forked off the release branch:<br />
|-<br />
|<br />
:<code>$ git checkout release</code><br />
:<code>$ git merge --no-ff ''my-topic''</code><br />
:<code>$ git push origin release</code><br />
and do:<br />
|-<br />
|<br />
:<code>$ git checkout master</code><br />
:<code>$ git merge --no-ff release</code><br />
:<code>$ git push origin master</code><br />
to merge the release branch back to master.<br />
<br />
:''(If the merge conflicts follow the printed instructions to resolve them.)''<br />
|align="center"|<br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.gerrit-merge</code>]<br />
<br/><br />
([http://schacon.github.com/git/git-push.html <code>push</code>] to [[Git/Workflow/Stage|topic stage]] and<br />
<br/><br />
<code>stage ITK merge ''my-topic''</code>)<br />
<br/><br />
[[Git/Workflow/Topic/Conflicts#Branch-to-Topic|Branch-to-Topic Conflict Resolution]]<br />
|}<br />
<br />
==Delete a Topic==<br />
<br />
After a topic has been merged upstream, delete your local branch for the topic.<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Checkout and update the '''master''' branch:<br />
|-<br />
|<br />
:<code>$ git checkout master</code><br />
:<code>$ git pullall</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
<br/><br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.pullall</code>]<br />
<br/><br />
([http://schacon.github.com/git/git-pull.html <code>pull</code>] and<br />
[http://schacon.github.com/git/git-submodule.html <code>submodule</code>] <code>update</code>)<br />
|-<br />
|<br />
Delete the local topic branch:<br />
|-<br />
|<br />
:<code>$ git branch -d ''my-topic''</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-branch.html <code>git help branch</code>]<br />
|-<br />
|<br />
The <code>branch -d</code> command works only when the topic branch has been correctly merged.<br />
Use <code>-D</code> instead of <code>-d</code> to force the deletion of an unmerged topic branch<br />
(warning - you could lose commits).<br />
|}</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK/Git/Develop&diff=52039ITK/Git/Develop2013-03-28T18:22:33Z<p>Xiaoxiao: /* Merge a Topic */</p>
<hr />
<div>__NOTOC__<br />
<br />
This page documents how to develop ITK through [http://git-scm.com Git].<br />
See our [[ITK/Git|table of contents]] for more information.<br />
<br />
<i><br />
Git is an extremely powerful version control tool that supports many different "workflows" for indivudal development and collaboration.<br />
Here we document procedures used by the ITK development community.<br />
In the interest of simplicity and brevity we do '''not''' provide an explanation of why we use this approach.<br />
Furthermore, this is '''not''' a Git tutorial.<br />
Please see our [[Git/Resources|Git resource links]] for third-party documentation, such as the [http://git-scm.com/book/ ProGit Book].<br />
</i><br />
<br />
==Setup==<br />
<br />
Before you begin, perform initial setup:<br />
<br />
{| style="width: 100%" cellspacing="0" cellpadding="0"<br />
|-<br />
|width=60%|<br />
1.<br />
Register [[ITK/Git/Account#Gerrit|Gerrit access]] and possibly [[ITK/Git/Account#Git|Git push access]].<br />
|-<br />
|<br />
2.<br />
Optionally download our [[Media:GitITKCheatSheet.pdf|one page PDF desk reference]].<br />
|-<br />
|<br />
3.<br />
Follow the [[ITK/Git/Download#Clone|download instructions]] to create a local ITK clone:<br />
|-<br />
|<br />
:<code>$ git clone git://itk.org/ITK.git</code><br />
|align="center"|<br />
[[Git/Trouble#Firewall_Blocks_Port_9418|Connection refused]]?<br />
|-<br />
|<br />
4.<br />
Run the developer setup script to prepare your ITK work tree and create Git command aliases used below:<br />
|-<br />
|<br />
:<code>$ ./Utilities/SetupForDevelopment.sh</code><br />
|align="center"|<br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/SetupForDevelopment.sh;hb=HEAD <code>SetupForDevelopment.sh</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Getting-Started-First-Time-Git-Setup Pro Git: Setup]<br />
|}<br />
<br />
==Workflow==<br />
<br />
ITK development uses a [[Git/Workflow/Topic|branchy workflow]] based on topic branches.<br />
Our collaboration workflow consists of three main steps:<br />
<br />
{| style="width: 100%" cellspacing="0" cellpadding="0"<br />
|-<br />
|width=60%|<br />
1.<br />
Local Development<br />
|-<br />
|<br />
:* [[#Update|Update]]<br />
|-<br />
|<br />
:* [[#Create_a_Topic|Create a Topic]]<br />
|-<br />
|<br />
2.<br />
Code Review<br />
|-<br />
|<br />
:* [[#Share_a_Topic|Share a Topic]] (requires [[ITK/Git/Account#Gerrit|Gerrit access]])<br />
|align="center"|<br />
[http://code.google.com/p/gerrit/ Gerrit Code Review]<br />
|-<br />
|<br />
:* [[#Revise_a_Topic|Revise a Topic]]<br />
|-<br />
|<br />
3.<br />
Integrate Changes<br />
|-<br />
|<br />
:* [[#Merge_a_Topic|Merge a Topic]] (requires [[ITK/Git/Account#Git|Git push access]])<br />
|-<br />
|<br />
:* [[#Delete_a_Topic|Delete a Topic]]<br />
|}<br />
<br />
==Update==<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Update your local '''master''' branch:<br />
|-<br />
|<br />
:<code>$ git checkout master</code><br />
:<code>$ git pullall</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
<br/><br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.pullall</code>]<br />
<br/><br />
([http://schacon.github.com/git/git-pull.html <code>pull</code>] and<br />
[http://schacon.github.com/git/git-submodule.html <code>submodule</code>] <code>update</code>)<br />
|}<br />
<br />
==Create a Topic==<br />
<br />
All new work must be committed on topic branches.<br />
Name topics like you might name functions: concise but precise.<br />
A reader should have a general idea of the feature or fix to be developed given just the branch name.<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
To start a new topic branch:<br />
|-<br />
|<br />
:<code>$ git fetch origin</code><br />
:{|<br />
|-<br />
|<br />
For new development, start the topic from <code>origin/master</code>:<br />
:<code>$ git checkout -b ''my-topic'' origin/master</code><br />
|-<br />
|<br />
For release branch fixes, start the topic from <code>origin/release</code>, and by convention use a topic name starting in "<code>release-</code>":<br />
:<code>$ git checkout -b ''my-topic'' origin/release</code><br />
|}<br />
|align="center"|<br />
[http://schacon.github.com/git/git-fetch.html <code>git help fetch</code>]<br />
<br/><br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
<br/><br />
[http://schacon.github.com/git/git-submodule.html <code>git help submodule</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging Pro Git: Basic Branching]<br />
|-<br />
|<br />
Edit files and create commits (repeat as needed):<br />
|-<br />
|<br />
:<code>$ edit ''file1'' ''file2'' ''file3''</code><br />
:''(To add data follow [[ITK/Git/Develop/Data#Add_Data|these instructions]].)''<br />
:<code>$ git add ''file1'' ''file2'' ''file3''</code><br />
:<code>$ git commit</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-add.html <code>git help add</code>]<br />
<br/><br />
[http://schacon.github.com/git/git-commit.html <code>git help commit</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Basics-Recording-Changes-to-the-Repository Pro Git: Recording Changes]<br />
|-<br />
|<br />
''(If your change modifies the "<code>Modules/ThirdParty/KWSys/src/KWSys</code>" directory please contribute directly to [[KWSys/Git|KWSys]] instead.)''<br />
|}<br />
<br />
==Share a Topic==<br />
<br />
When a topic is ready for review and possible inclusion, share it by pushing to Gerrit.<br />
Be sure you have registered for [[ITK/Git/Account#Gerrit|Gerrit access]].<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Checkout the topic if it is not your current branch:<br />
|-<br />
|<br />
:<code>$ git checkout ''my-topic''</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
|-<br />
|<br />
Check what commits will be pushed to Gerrit for review:<br />
|-<br />
|<br />
:<code>$ git prepush</code><br />
or if you started the topic from the release branch:<br />
:<code>$ git push gerrit HEAD:refs/for/release/''my-topic'' </code> <br />
|align="center"|<br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.prepush</code>]<br />
<br/><br />
([http://schacon.github.com/git/git-log.html <code>log</code>] <code>origin/master..</code>)<br />
|-<br />
|<br />
Push commits in your topic branch for review by the community:<br />
|-<br />
|<br />
:<code>$ git gerrit-push</code><br />
:''(If the topic adds data see [[ITK/Git/Develop/Data#Push|this note]].)''<br />
|align="center"|<br />
[[ITK/Git/Account#Firewall_blocks_SSH_traffic|Connection refused]]?<br />
<br/><br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.gerrit-push</code>]<br />
<br/><br />
([http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/Git/git-gerrit-push;hb=HEAD <code>Utilities/Git/git-gerrit-push</code>])<br />
|}<br />
Find your change in the [http://review.source.kitware.com/p/ITK ITK Gerrit] instance and add [[ITK/Gerrit/Reviewers|reviewers]].<br />
<br />
==Revise a Topic==<br />
<br />
If a topic is approved during Gerrit review, skip to the [[#Merge_a_Topic|next step]].<br />
Otherwise, revise the topic and push it back to Gerrit for another review.<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Checkout the topic if it is not your current branch:<br />
|-<br />
|<br />
:<code>$ git checkout ''my-topic''</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
|-<br />
|<br />
To revise the most recent commit on the topic edit files and add changes normally and then amend the commit:<br />
|-<br />
|<br />
:<code>$ git commit --amend</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-commit.html <code>git help commit</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Tools-Rewriting-History#Changing-the-Last-Commit Pro Git: Changing the Last Commit]<br />
|-<br />
|<br />
To revise commits further back on the topic, say the <code>3</code>rd commit back:<br />
|-<br />
|<br />
:<code>$ git rebase -i HEAD~3</code><br />
''(Substitute the correct number of commits back, as low as ''<code>1</code>''.)''<br />
<br />
Follow Git's interactive instructions.<br />
Preserve the <code>Change-Id:</code> line at the bottom of each commit message.<br />
|align="center"|<br />
[http://schacon.github.com/git/git-rebase.html <code>git help rebase</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Tools-Rewriting-History#Changing-Multiple-Commit-Messages Pro Git: Changing Multiple Commits]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Branching-Rebasing Pro Git: Rebasing]<br />
|-<br />
|<br />
Return to the [[#Share_a_Topic|previous step]] to share the revised topic.<br />
|}<br />
<br />
==Merge a Topic==<br />
'''Only authorized developers with [[ITK/Git/Account#Git|Git push access]] to <code>itk.org</code> may perform this step.'''<br />
After a feature topic has been reviewed and approved in Gerrit, merge it into the upstream repository.<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Checkout the topic if it is not your current branch:<br />
|-<br />
|<br />
:<code>$ git checkout ''my-topic''</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
|-<br />
|<br />
Merge the topic, which is originally forked off the master branch, to master branch:<br />
|-<br />
|<br />
:<code>$ git gerrit-merge</code><br />
<br />
For bug fixes that are ready to be included in the next release, please email the release manager<br />
Matt Mccormick([[matt.mccormick@kitware.com)]] for assistance.<br />
Here are the recommended steps to merge a topic to both release and master branches, assuming the topic<br />
branch is forked off the release branch:<br />
|-<br />
|<br />
:<code>$ git checkout release</code><br />
:<code>$ git merge --no-ff ''my-topic''</code><br />
:<code>$ git push origin release</code><br />
and do:<br />
|-<br />
|<br />
:<code>$ git checkout master</code><br />
:<code>$ git merge --no-ff release</code><br />
:<code>$ git push origin master</code><br />
to merge the release branch back to master.<br />
<br />
:''(If the merge conflicts follow the printed instructions to resolve them.)''<br />
|align="center"|<br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.gerrit-merge</code>]<br />
<br/><br />
([http://schacon.github.com/git/git-push.html <code>push</code>] to [[Git/Workflow/Stage|topic stage]] and<br />
<br/><br />
<code>stage ITK merge ''my-topic''</code>)<br />
<br/><br />
[[Git/Workflow/Topic/Conflicts#Branch-to-Topic|Branch-to-Topic Conflict Resolution]]<br />
|}<br />
<br />
==Delete a Topic==<br />
<br />
After a topic has been merged upstream, delete your local branch for the topic.<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Checkout and update the '''master''' branch:<br />
|-<br />
|<br />
:<code>$ git checkout master</code><br />
:<code>$ git pullall</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
<br/><br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.pullall</code>]<br />
<br/><br />
([http://schacon.github.com/git/git-pull.html <code>pull</code>] and<br />
[http://schacon.github.com/git/git-submodule.html <code>submodule</code>] <code>update</code>)<br />
|-<br />
|<br />
Delete the local topic branch:<br />
|-<br />
|<br />
:<code>$ git branch -d ''my-topic''</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-branch.html <code>git help branch</code>]<br />
|-<br />
|<br />
The <code>branch -d</code> command works only when the topic branch has been correctly merged.<br />
Use <code>-D</code> instead of <code>-d</code> to force the deletion of an unmerged topic branch<br />
(warning - you could lose commits).<br />
|}</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK/Git/Develop&diff=52038ITK/Git/Develop2013-03-28T18:21:43Z<p>Xiaoxiao: /* Merge a Topic */</p>
<hr />
<div>__NOTOC__<br />
<br />
This page documents how to develop ITK through [http://git-scm.com Git].<br />
See our [[ITK/Git|table of contents]] for more information.<br />
<br />
<i><br />
Git is an extremely powerful version control tool that supports many different "workflows" for indivudal development and collaboration.<br />
Here we document procedures used by the ITK development community.<br />
In the interest of simplicity and brevity we do '''not''' provide an explanation of why we use this approach.<br />
Furthermore, this is '''not''' a Git tutorial.<br />
Please see our [[Git/Resources|Git resource links]] for third-party documentation, such as the [http://git-scm.com/book/ ProGit Book].<br />
</i><br />
<br />
==Setup==<br />
<br />
Before you begin, perform initial setup:<br />
<br />
{| style="width: 100%" cellspacing="0" cellpadding="0"<br />
|-<br />
|width=60%|<br />
1.<br />
Register [[ITK/Git/Account#Gerrit|Gerrit access]] and possibly [[ITK/Git/Account#Git|Git push access]].<br />
|-<br />
|<br />
2.<br />
Optionally download our [[Media:GitITKCheatSheet.pdf|one page PDF desk reference]].<br />
|-<br />
|<br />
3.<br />
Follow the [[ITK/Git/Download#Clone|download instructions]] to create a local ITK clone:<br />
|-<br />
|<br />
:<code>$ git clone git://itk.org/ITK.git</code><br />
|align="center"|<br />
[[Git/Trouble#Firewall_Blocks_Port_9418|Connection refused]]?<br />
|-<br />
|<br />
4.<br />
Run the developer setup script to prepare your ITK work tree and create Git command aliases used below:<br />
|-<br />
|<br />
:<code>$ ./Utilities/SetupForDevelopment.sh</code><br />
|align="center"|<br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/SetupForDevelopment.sh;hb=HEAD <code>SetupForDevelopment.sh</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Getting-Started-First-Time-Git-Setup Pro Git: Setup]<br />
|}<br />
<br />
==Workflow==<br />
<br />
ITK development uses a [[Git/Workflow/Topic|branchy workflow]] based on topic branches.<br />
Our collaboration workflow consists of three main steps:<br />
<br />
{| style="width: 100%" cellspacing="0" cellpadding="0"<br />
|-<br />
|width=60%|<br />
1.<br />
Local Development<br />
|-<br />
|<br />
:* [[#Update|Update]]<br />
|-<br />
|<br />
:* [[#Create_a_Topic|Create a Topic]]<br />
|-<br />
|<br />
2.<br />
Code Review<br />
|-<br />
|<br />
:* [[#Share_a_Topic|Share a Topic]] (requires [[ITK/Git/Account#Gerrit|Gerrit access]])<br />
|align="center"|<br />
[http://code.google.com/p/gerrit/ Gerrit Code Review]<br />
|-<br />
|<br />
:* [[#Revise_a_Topic|Revise a Topic]]<br />
|-<br />
|<br />
3.<br />
Integrate Changes<br />
|-<br />
|<br />
:* [[#Merge_a_Topic|Merge a Topic]] (requires [[ITK/Git/Account#Git|Git push access]])<br />
|-<br />
|<br />
:* [[#Delete_a_Topic|Delete a Topic]]<br />
|}<br />
<br />
==Update==<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Update your local '''master''' branch:<br />
|-<br />
|<br />
:<code>$ git checkout master</code><br />
:<code>$ git pullall</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
<br/><br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.pullall</code>]<br />
<br/><br />
([http://schacon.github.com/git/git-pull.html <code>pull</code>] and<br />
[http://schacon.github.com/git/git-submodule.html <code>submodule</code>] <code>update</code>)<br />
|}<br />
<br />
==Create a Topic==<br />
<br />
All new work must be committed on topic branches.<br />
Name topics like you might name functions: concise but precise.<br />
A reader should have a general idea of the feature or fix to be developed given just the branch name.<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
To start a new topic branch:<br />
|-<br />
|<br />
:<code>$ git fetch origin</code><br />
:{|<br />
|-<br />
|<br />
For new development, start the topic from <code>origin/master</code>:<br />
:<code>$ git checkout -b ''my-topic'' origin/master</code><br />
|-<br />
|<br />
For release branch fixes, start the topic from <code>origin/release</code>, and by convention use a topic name starting in "<code>release-</code>":<br />
:<code>$ git checkout -b ''my-topic'' origin/release</code><br />
|}<br />
|align="center"|<br />
[http://schacon.github.com/git/git-fetch.html <code>git help fetch</code>]<br />
<br/><br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
<br/><br />
[http://schacon.github.com/git/git-submodule.html <code>git help submodule</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging Pro Git: Basic Branching]<br />
|-<br />
|<br />
Edit files and create commits (repeat as needed):<br />
|-<br />
|<br />
:<code>$ edit ''file1'' ''file2'' ''file3''</code><br />
:''(To add data follow [[ITK/Git/Develop/Data#Add_Data|these instructions]].)''<br />
:<code>$ git add ''file1'' ''file2'' ''file3''</code><br />
:<code>$ git commit</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-add.html <code>git help add</code>]<br />
<br/><br />
[http://schacon.github.com/git/git-commit.html <code>git help commit</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Basics-Recording-Changes-to-the-Repository Pro Git: Recording Changes]<br />
|-<br />
|<br />
''(If your change modifies the "<code>Modules/ThirdParty/KWSys/src/KWSys</code>" directory please contribute directly to [[KWSys/Git|KWSys]] instead.)''<br />
|}<br />
<br />
==Share a Topic==<br />
<br />
When a topic is ready for review and possible inclusion, share it by pushing to Gerrit.<br />
Be sure you have registered for [[ITK/Git/Account#Gerrit|Gerrit access]].<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Checkout the topic if it is not your current branch:<br />
|-<br />
|<br />
:<code>$ git checkout ''my-topic''</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
|-<br />
|<br />
Check what commits will be pushed to Gerrit for review:<br />
|-<br />
|<br />
:<code>$ git prepush</code><br />
or if you started the topic from the release branch:<br />
:<code>$ git push gerrit HEAD:refs/for/release/''my-topic'' </code> <br />
|align="center"|<br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.prepush</code>]<br />
<br/><br />
([http://schacon.github.com/git/git-log.html <code>log</code>] <code>origin/master..</code>)<br />
|-<br />
|<br />
Push commits in your topic branch for review by the community:<br />
|-<br />
|<br />
:<code>$ git gerrit-push</code><br />
:''(If the topic adds data see [[ITK/Git/Develop/Data#Push|this note]].)''<br />
|align="center"|<br />
[[ITK/Git/Account#Firewall_blocks_SSH_traffic|Connection refused]]?<br />
<br/><br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.gerrit-push</code>]<br />
<br/><br />
([http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/Git/git-gerrit-push;hb=HEAD <code>Utilities/Git/git-gerrit-push</code>])<br />
|}<br />
Find your change in the [http://review.source.kitware.com/p/ITK ITK Gerrit] instance and add [[ITK/Gerrit/Reviewers|reviewers]].<br />
<br />
==Revise a Topic==<br />
<br />
If a topic is approved during Gerrit review, skip to the [[#Merge_a_Topic|next step]].<br />
Otherwise, revise the topic and push it back to Gerrit for another review.<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Checkout the topic if it is not your current branch:<br />
|-<br />
|<br />
:<code>$ git checkout ''my-topic''</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
|-<br />
|<br />
To revise the most recent commit on the topic edit files and add changes normally and then amend the commit:<br />
|-<br />
|<br />
:<code>$ git commit --amend</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-commit.html <code>git help commit</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Tools-Rewriting-History#Changing-the-Last-Commit Pro Git: Changing the Last Commit]<br />
|-<br />
|<br />
To revise commits further back on the topic, say the <code>3</code>rd commit back:<br />
|-<br />
|<br />
:<code>$ git rebase -i HEAD~3</code><br />
''(Substitute the correct number of commits back, as low as ''<code>1</code>''.)''<br />
<br />
Follow Git's interactive instructions.<br />
Preserve the <code>Change-Id:</code> line at the bottom of each commit message.<br />
|align="center"|<br />
[http://schacon.github.com/git/git-rebase.html <code>git help rebase</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Tools-Rewriting-History#Changing-Multiple-Commit-Messages Pro Git: Changing Multiple Commits]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Branching-Rebasing Pro Git: Rebasing]<br />
|-<br />
|<br />
Return to the [[#Share_a_Topic|previous step]] to share the revised topic.<br />
|}<br />
<br />
==Merge a Topic==<br />
<br />
After a feature topic has been reviewed and approved in Gerrit, merge it into the upstream repository.<br />
'''Only authorized developers with [[ITK/Git/Account#Git|Git push access]] to <code>itk.org</code> may perform this step.'''<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Checkout the topic if it is not your current branch:<br />
|-<br />
|<br />
:<code>$ git checkout ''my-topic''</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
|-<br />
|<br />
Merge the topic, which is originally forked off the master branch, to master branch:<br />
|-<br />
|<br />
:<code>$ git gerrit-merge</code><br />
<br />
For bug fixes that are ready to be included in the next release, please email the release manager<br />
Matt Mccormick([[matt.mccormick@kitware.com)]] for assistance.<br />
Here are the recommended steps to merge a topic to both release and master branches, assuming the topic<br />
branch is forked off the release branch:<br />
|-<br />
|<br />
:<code>$ git checkout release</code><br />
:<code>$ git merge --no-ff ''my-topic''</code><br />
:<code>$ git push origin release</code><br />
and do:<br />
|-<br />
|<br />
:<code>$ git checkout master</code><br />
:<code>$ git merge --no-ff release</code><br />
:<code>$ git push origin master</code><br />
to merge the release branch back to master.<br />
<br />
:''(If the merge conflicts follow the printed instructions to resolve them.)''<br />
|align="center"|<br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.gerrit-merge</code>]<br />
<br/><br />
([http://schacon.github.com/git/git-push.html <code>push</code>] to [[Git/Workflow/Stage|topic stage]] and<br />
<br/><br />
<code>stage ITK merge ''my-topic''</code>)<br />
<br/><br />
[[Git/Workflow/Topic/Conflicts#Branch-to-Topic|Branch-to-Topic Conflict Resolution]]<br />
|}<br />
<br />
==Delete a Topic==<br />
<br />
After a topic has been merged upstream, delete your local branch for the topic.<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Checkout and update the '''master''' branch:<br />
|-<br />
|<br />
:<code>$ git checkout master</code><br />
:<code>$ git pullall</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
<br/><br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.pullall</code>]<br />
<br/><br />
([http://schacon.github.com/git/git-pull.html <code>pull</code>] and<br />
[http://schacon.github.com/git/git-submodule.html <code>submodule</code>] <code>update</code>)<br />
|-<br />
|<br />
Delete the local topic branch:<br />
|-<br />
|<br />
:<code>$ git branch -d ''my-topic''</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-branch.html <code>git help branch</code>]<br />
|-<br />
|<br />
The <code>branch -d</code> command works only when the topic branch has been correctly merged.<br />
Use <code>-D</code> instead of <code>-d</code> to force the deletion of an unmerged topic branch<br />
(warning - you could lose commits).<br />
|}</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK/Git/Develop&diff=52037ITK/Git/Develop2013-03-28T18:19:55Z<p>Xiaoxiao: /* Share a Topic */</p>
<hr />
<div>__NOTOC__<br />
<br />
This page documents how to develop ITK through [http://git-scm.com Git].<br />
See our [[ITK/Git|table of contents]] for more information.<br />
<br />
<i><br />
Git is an extremely powerful version control tool that supports many different "workflows" for indivudal development and collaboration.<br />
Here we document procedures used by the ITK development community.<br />
In the interest of simplicity and brevity we do '''not''' provide an explanation of why we use this approach.<br />
Furthermore, this is '''not''' a Git tutorial.<br />
Please see our [[Git/Resources|Git resource links]] for third-party documentation, such as the [http://git-scm.com/book/ ProGit Book].<br />
</i><br />
<br />
==Setup==<br />
<br />
Before you begin, perform initial setup:<br />
<br />
{| style="width: 100%" cellspacing="0" cellpadding="0"<br />
|-<br />
|width=60%|<br />
1.<br />
Register [[ITK/Git/Account#Gerrit|Gerrit access]] and possibly [[ITK/Git/Account#Git|Git push access]].<br />
|-<br />
|<br />
2.<br />
Optionally download our [[Media:GitITKCheatSheet.pdf|one page PDF desk reference]].<br />
|-<br />
|<br />
3.<br />
Follow the [[ITK/Git/Download#Clone|download instructions]] to create a local ITK clone:<br />
|-<br />
|<br />
:<code>$ git clone git://itk.org/ITK.git</code><br />
|align="center"|<br />
[[Git/Trouble#Firewall_Blocks_Port_9418|Connection refused]]?<br />
|-<br />
|<br />
4.<br />
Run the developer setup script to prepare your ITK work tree and create Git command aliases used below:<br />
|-<br />
|<br />
:<code>$ ./Utilities/SetupForDevelopment.sh</code><br />
|align="center"|<br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/SetupForDevelopment.sh;hb=HEAD <code>SetupForDevelopment.sh</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Getting-Started-First-Time-Git-Setup Pro Git: Setup]<br />
|}<br />
<br />
==Workflow==<br />
<br />
ITK development uses a [[Git/Workflow/Topic|branchy workflow]] based on topic branches.<br />
Our collaboration workflow consists of three main steps:<br />
<br />
{| style="width: 100%" cellspacing="0" cellpadding="0"<br />
|-<br />
|width=60%|<br />
1.<br />
Local Development<br />
|-<br />
|<br />
:* [[#Update|Update]]<br />
|-<br />
|<br />
:* [[#Create_a_Topic|Create a Topic]]<br />
|-<br />
|<br />
2.<br />
Code Review<br />
|-<br />
|<br />
:* [[#Share_a_Topic|Share a Topic]] (requires [[ITK/Git/Account#Gerrit|Gerrit access]])<br />
|align="center"|<br />
[http://code.google.com/p/gerrit/ Gerrit Code Review]<br />
|-<br />
|<br />
:* [[#Revise_a_Topic|Revise a Topic]]<br />
|-<br />
|<br />
3.<br />
Integrate Changes<br />
|-<br />
|<br />
:* [[#Merge_a_Topic|Merge a Topic]] (requires [[ITK/Git/Account#Git|Git push access]])<br />
|-<br />
|<br />
:* [[#Delete_a_Topic|Delete a Topic]]<br />
|}<br />
<br />
==Update==<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Update your local '''master''' branch:<br />
|-<br />
|<br />
:<code>$ git checkout master</code><br />
:<code>$ git pullall</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
<br/><br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.pullall</code>]<br />
<br/><br />
([http://schacon.github.com/git/git-pull.html <code>pull</code>] and<br />
[http://schacon.github.com/git/git-submodule.html <code>submodule</code>] <code>update</code>)<br />
|}<br />
<br />
==Create a Topic==<br />
<br />
All new work must be committed on topic branches.<br />
Name topics like you might name functions: concise but precise.<br />
A reader should have a general idea of the feature or fix to be developed given just the branch name.<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
To start a new topic branch:<br />
|-<br />
|<br />
:<code>$ git fetch origin</code><br />
:{|<br />
|-<br />
|<br />
For new development, start the topic from <code>origin/master</code>:<br />
:<code>$ git checkout -b ''my-topic'' origin/master</code><br />
|-<br />
|<br />
For release branch fixes, start the topic from <code>origin/release</code>, and by convention use a topic name starting in "<code>release-</code>":<br />
:<code>$ git checkout -b ''my-topic'' origin/release</code><br />
|}<br />
|align="center"|<br />
[http://schacon.github.com/git/git-fetch.html <code>git help fetch</code>]<br />
<br/><br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
<br/><br />
[http://schacon.github.com/git/git-submodule.html <code>git help submodule</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging Pro Git: Basic Branching]<br />
|-<br />
|<br />
Edit files and create commits (repeat as needed):<br />
|-<br />
|<br />
:<code>$ edit ''file1'' ''file2'' ''file3''</code><br />
:''(To add data follow [[ITK/Git/Develop/Data#Add_Data|these instructions]].)''<br />
:<code>$ git add ''file1'' ''file2'' ''file3''</code><br />
:<code>$ git commit</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-add.html <code>git help add</code>]<br />
<br/><br />
[http://schacon.github.com/git/git-commit.html <code>git help commit</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Basics-Recording-Changes-to-the-Repository Pro Git: Recording Changes]<br />
|-<br />
|<br />
''(If your change modifies the "<code>Modules/ThirdParty/KWSys/src/KWSys</code>" directory please contribute directly to [[KWSys/Git|KWSys]] instead.)''<br />
|}<br />
<br />
==Share a Topic==<br />
<br />
When a topic is ready for review and possible inclusion, share it by pushing to Gerrit.<br />
Be sure you have registered for [[ITK/Git/Account#Gerrit|Gerrit access]].<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Checkout the topic if it is not your current branch:<br />
|-<br />
|<br />
:<code>$ git checkout ''my-topic''</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
|-<br />
|<br />
Check what commits will be pushed to Gerrit for review:<br />
|-<br />
|<br />
:<code>$ git prepush</code><br />
or if you started the topic from the release branch:<br />
:<code>$ git push gerrit HEAD:refs/for/release/''my-topic'' </code> <br />
|align="center"|<br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.prepush</code>]<br />
<br/><br />
([http://schacon.github.com/git/git-log.html <code>log</code>] <code>origin/master..</code>)<br />
|-<br />
|<br />
Push commits in your topic branch for review by the community:<br />
|-<br />
|<br />
:<code>$ git gerrit-push</code><br />
:''(If the topic adds data see [[ITK/Git/Develop/Data#Push|this note]].)''<br />
|align="center"|<br />
[[ITK/Git/Account#Firewall_blocks_SSH_traffic|Connection refused]]?<br />
<br/><br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.gerrit-push</code>]<br />
<br/><br />
([http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/Git/git-gerrit-push;hb=HEAD <code>Utilities/Git/git-gerrit-push</code>])<br />
|}<br />
Find your change in the [http://review.source.kitware.com/p/ITK ITK Gerrit] instance and add [[ITK/Gerrit/Reviewers|reviewers]].<br />
<br />
==Revise a Topic==<br />
<br />
If a topic is approved during Gerrit review, skip to the [[#Merge_a_Topic|next step]].<br />
Otherwise, revise the topic and push it back to Gerrit for another review.<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Checkout the topic if it is not your current branch:<br />
|-<br />
|<br />
:<code>$ git checkout ''my-topic''</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
|-<br />
|<br />
To revise the most recent commit on the topic edit files and add changes normally and then amend the commit:<br />
|-<br />
|<br />
:<code>$ git commit --amend</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-commit.html <code>git help commit</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Tools-Rewriting-History#Changing-the-Last-Commit Pro Git: Changing the Last Commit]<br />
|-<br />
|<br />
To revise commits further back on the topic, say the <code>3</code>rd commit back:<br />
|-<br />
|<br />
:<code>$ git rebase -i HEAD~3</code><br />
''(Substitute the correct number of commits back, as low as ''<code>1</code>''.)''<br />
<br />
Follow Git's interactive instructions.<br />
Preserve the <code>Change-Id:</code> line at the bottom of each commit message.<br />
|align="center"|<br />
[http://schacon.github.com/git/git-rebase.html <code>git help rebase</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Tools-Rewriting-History#Changing-Multiple-Commit-Messages Pro Git: Changing Multiple Commits]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Branching-Rebasing Pro Git: Rebasing]<br />
|-<br />
|<br />
Return to the [[#Share_a_Topic|previous step]] to share the revised topic.<br />
|}<br />
<br />
==Merge a Topic==<br />
<br />
After a feature topic has been reviewed and approved in Gerrit, merge it into the upstream repository.<br />
'''Only authorized developers with [[ITK/Git/Account#Git|Git push access]] to <code>itk.org</code> may perform this step.'''<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Checkout the topic if it is not your current branch:<br />
|-<br />
|<br />
:<code>$ git checkout ''my-topic''</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
|-<br />
|<br />
Merge the topic, which is originally forked off the master branch, to master branch:<br />
|-<br />
|<br />
:<code>$ git gerrit-merge</code><br />
<br />
For bug fixes that are ready to be included in the next release, please email the release manager<br />
Matt Mccormick([[matt.mccormick@kitware.com)]] for assistance.<br />
Here are the recommended steps to merge a topic to both release and master branches, assuming the topic<br />
branch is forked off the release branch:<br />
|-<br />
|<br />
:<code>$ git checkout release</code><br />
:<code>$ git merge --no-ff ''my-topic''</code><br />
:<code>$ git push origin/release</code><br />
and do:<br />
|-<br />
|<br />
:<code>$ git checkout master</code><br />
:<code>$ git merge --no-ff release</code><br />
:<code>$ git push origin/master</code><br />
to merge the release branch back to master.<br />
<br />
:''(If the merge conflicts follow the printed instructions to resolve them.)''<br />
|align="center"|<br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.gerrit-merge</code>]<br />
<br/><br />
([http://schacon.github.com/git/git-push.html <code>push</code>] to [[Git/Workflow/Stage|topic stage]] and<br />
<br/><br />
<code>stage ITK merge ''my-topic''</code>)<br />
<br/><br />
[[Git/Workflow/Topic/Conflicts#Branch-to-Topic|Branch-to-Topic Conflict Resolution]]<br />
|}<br />
<br />
==Delete a Topic==<br />
<br />
After a topic has been merged upstream, delete your local branch for the topic.<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Checkout and update the '''master''' branch:<br />
|-<br />
|<br />
:<code>$ git checkout master</code><br />
:<code>$ git pullall</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
<br/><br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.pullall</code>]<br />
<br/><br />
([http://schacon.github.com/git/git-pull.html <code>pull</code>] and<br />
[http://schacon.github.com/git/git-submodule.html <code>submodule</code>] <code>update</code>)<br />
|-<br />
|<br />
Delete the local topic branch:<br />
|-<br />
|<br />
:<code>$ git branch -d ''my-topic''</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-branch.html <code>git help branch</code>]<br />
|-<br />
|<br />
The <code>branch -d</code> command works only when the topic branch has been correctly merged.<br />
Use <code>-D</code> instead of <code>-d</code> to force the deletion of an unmerged topic branch<br />
(warning - you could lose commits).<br />
|}</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK/Git/Develop&diff=52036ITK/Git/Develop2013-03-28T18:19:39Z<p>Xiaoxiao: /* Merge a Topic */</p>
<hr />
<div>__NOTOC__<br />
<br />
This page documents how to develop ITK through [http://git-scm.com Git].<br />
See our [[ITK/Git|table of contents]] for more information.<br />
<br />
<i><br />
Git is an extremely powerful version control tool that supports many different "workflows" for indivudal development and collaboration.<br />
Here we document procedures used by the ITK development community.<br />
In the interest of simplicity and brevity we do '''not''' provide an explanation of why we use this approach.<br />
Furthermore, this is '''not''' a Git tutorial.<br />
Please see our [[Git/Resources|Git resource links]] for third-party documentation, such as the [http://git-scm.com/book/ ProGit Book].<br />
</i><br />
<br />
==Setup==<br />
<br />
Before you begin, perform initial setup:<br />
<br />
{| style="width: 100%" cellspacing="0" cellpadding="0"<br />
|-<br />
|width=60%|<br />
1.<br />
Register [[ITK/Git/Account#Gerrit|Gerrit access]] and possibly [[ITK/Git/Account#Git|Git push access]].<br />
|-<br />
|<br />
2.<br />
Optionally download our [[Media:GitITKCheatSheet.pdf|one page PDF desk reference]].<br />
|-<br />
|<br />
3.<br />
Follow the [[ITK/Git/Download#Clone|download instructions]] to create a local ITK clone:<br />
|-<br />
|<br />
:<code>$ git clone git://itk.org/ITK.git</code><br />
|align="center"|<br />
[[Git/Trouble#Firewall_Blocks_Port_9418|Connection refused]]?<br />
|-<br />
|<br />
4.<br />
Run the developer setup script to prepare your ITK work tree and create Git command aliases used below:<br />
|-<br />
|<br />
:<code>$ ./Utilities/SetupForDevelopment.sh</code><br />
|align="center"|<br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/SetupForDevelopment.sh;hb=HEAD <code>SetupForDevelopment.sh</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Getting-Started-First-Time-Git-Setup Pro Git: Setup]<br />
|}<br />
<br />
==Workflow==<br />
<br />
ITK development uses a [[Git/Workflow/Topic|branchy workflow]] based on topic branches.<br />
Our collaboration workflow consists of three main steps:<br />
<br />
{| style="width: 100%" cellspacing="0" cellpadding="0"<br />
|-<br />
|width=60%|<br />
1.<br />
Local Development<br />
|-<br />
|<br />
:* [[#Update|Update]]<br />
|-<br />
|<br />
:* [[#Create_a_Topic|Create a Topic]]<br />
|-<br />
|<br />
2.<br />
Code Review<br />
|-<br />
|<br />
:* [[#Share_a_Topic|Share a Topic]] (requires [[ITK/Git/Account#Gerrit|Gerrit access]])<br />
|align="center"|<br />
[http://code.google.com/p/gerrit/ Gerrit Code Review]<br />
|-<br />
|<br />
:* [[#Revise_a_Topic|Revise a Topic]]<br />
|-<br />
|<br />
3.<br />
Integrate Changes<br />
|-<br />
|<br />
:* [[#Merge_a_Topic|Merge a Topic]] (requires [[ITK/Git/Account#Git|Git push access]])<br />
|-<br />
|<br />
:* [[#Delete_a_Topic|Delete a Topic]]<br />
|}<br />
<br />
==Update==<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Update your local '''master''' branch:<br />
|-<br />
|<br />
:<code>$ git checkout master</code><br />
:<code>$ git pullall</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
<br/><br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.pullall</code>]<br />
<br/><br />
([http://schacon.github.com/git/git-pull.html <code>pull</code>] and<br />
[http://schacon.github.com/git/git-submodule.html <code>submodule</code>] <code>update</code>)<br />
|}<br />
<br />
==Create a Topic==<br />
<br />
All new work must be committed on topic branches.<br />
Name topics like you might name functions: concise but precise.<br />
A reader should have a general idea of the feature or fix to be developed given just the branch name.<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
To start a new topic branch:<br />
|-<br />
|<br />
:<code>$ git fetch origin</code><br />
:{|<br />
|-<br />
|<br />
For new development, start the topic from <code>origin/master</code>:<br />
:<code>$ git checkout -b ''my-topic'' origin/master</code><br />
|-<br />
|<br />
For release branch fixes, start the topic from <code>origin/release</code>, and by convention use a topic name starting in "<code>release-</code>":<br />
:<code>$ git checkout -b ''my-topic'' origin/release</code><br />
|}<br />
|align="center"|<br />
[http://schacon.github.com/git/git-fetch.html <code>git help fetch</code>]<br />
<br/><br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
<br/><br />
[http://schacon.github.com/git/git-submodule.html <code>git help submodule</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging Pro Git: Basic Branching]<br />
|-<br />
|<br />
Edit files and create commits (repeat as needed):<br />
|-<br />
|<br />
:<code>$ edit ''file1'' ''file2'' ''file3''</code><br />
:''(To add data follow [[ITK/Git/Develop/Data#Add_Data|these instructions]].)''<br />
:<code>$ git add ''file1'' ''file2'' ''file3''</code><br />
:<code>$ git commit</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-add.html <code>git help add</code>]<br />
<br/><br />
[http://schacon.github.com/git/git-commit.html <code>git help commit</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Basics-Recording-Changes-to-the-Repository Pro Git: Recording Changes]<br />
|-<br />
|<br />
''(If your change modifies the "<code>Modules/ThirdParty/KWSys/src/KWSys</code>" directory please contribute directly to [[KWSys/Git|KWSys]] instead.)''<br />
|}<br />
<br />
==Share a Topic==<br />
<br />
When a topic is ready for review and possible inclusion, share it by pushing to Gerrit.<br />
Be sure you have registered for [[ITK/Git/Account#Gerrit|Gerrit access]].<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Checkout the topic if it is not your current branch:<br />
|-<br />
|<br />
:<code>$ git checkout ''my-topic''</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
|-<br />
|<br />
Check what commits will be pushed to Gerrit for review:<br />
|-<br />
|<br />
:<code>$ git prepush</code><br />
or if you started the topic from the release branch:<br />
:<code>$ git push gerrit HEAD:refs/for/release/my-topic </code> <br />
|align="center"|<br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.prepush</code>]<br />
<br/><br />
([http://schacon.github.com/git/git-log.html <code>log</code>] <code>origin/master..</code>)<br />
|-<br />
|<br />
Push commits in your topic branch for review by the community:<br />
|-<br />
|<br />
:<code>$ git gerrit-push</code><br />
:''(If the topic adds data see [[ITK/Git/Develop/Data#Push|this note]].)''<br />
|align="center"|<br />
[[ITK/Git/Account#Firewall_blocks_SSH_traffic|Connection refused]]?<br />
<br/><br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.gerrit-push</code>]<br />
<br/><br />
([http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/Git/git-gerrit-push;hb=HEAD <code>Utilities/Git/git-gerrit-push</code>])<br />
|}<br />
Find your change in the [http://review.source.kitware.com/p/ITK ITK Gerrit] instance and add [[ITK/Gerrit/Reviewers|reviewers]].<br />
<br />
==Revise a Topic==<br />
<br />
If a topic is approved during Gerrit review, skip to the [[#Merge_a_Topic|next step]].<br />
Otherwise, revise the topic and push it back to Gerrit for another review.<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Checkout the topic if it is not your current branch:<br />
|-<br />
|<br />
:<code>$ git checkout ''my-topic''</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
|-<br />
|<br />
To revise the most recent commit on the topic edit files and add changes normally and then amend the commit:<br />
|-<br />
|<br />
:<code>$ git commit --amend</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-commit.html <code>git help commit</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Tools-Rewriting-History#Changing-the-Last-Commit Pro Git: Changing the Last Commit]<br />
|-<br />
|<br />
To revise commits further back on the topic, say the <code>3</code>rd commit back:<br />
|-<br />
|<br />
:<code>$ git rebase -i HEAD~3</code><br />
''(Substitute the correct number of commits back, as low as ''<code>1</code>''.)''<br />
<br />
Follow Git's interactive instructions.<br />
Preserve the <code>Change-Id:</code> line at the bottom of each commit message.<br />
|align="center"|<br />
[http://schacon.github.com/git/git-rebase.html <code>git help rebase</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Tools-Rewriting-History#Changing-Multiple-Commit-Messages Pro Git: Changing Multiple Commits]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Branching-Rebasing Pro Git: Rebasing]<br />
|-<br />
|<br />
Return to the [[#Share_a_Topic|previous step]] to share the revised topic.<br />
|}<br />
<br />
==Merge a Topic==<br />
<br />
After a feature topic has been reviewed and approved in Gerrit, merge it into the upstream repository.<br />
'''Only authorized developers with [[ITK/Git/Account#Git|Git push access]] to <code>itk.org</code> may perform this step.'''<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Checkout the topic if it is not your current branch:<br />
|-<br />
|<br />
:<code>$ git checkout ''my-topic''</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
|-<br />
|<br />
Merge the topic, which is originally forked off the master branch, to master branch:<br />
|-<br />
|<br />
:<code>$ git gerrit-merge</code><br />
<br />
For bug fixes that are ready to be included in the next release, please email the release manager<br />
Matt Mccormick([[matt.mccormick@kitware.com)]] for assistance.<br />
Here are the recommended steps to merge a topic to both release and master branches, assuming the topic<br />
branch is forked off the release branch:<br />
|-<br />
|<br />
:<code>$ git checkout release</code><br />
:<code>$ git merge --no-ff ''my-topic''</code><br />
:<code>$ git push origin/release</code><br />
and do:<br />
|-<br />
|<br />
:<code>$ git checkout master</code><br />
:<code>$ git merge --no-ff release</code><br />
:<code>$ git push origin/master</code><br />
to merge the release branch back to master.<br />
<br />
:''(If the merge conflicts follow the printed instructions to resolve them.)''<br />
|align="center"|<br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.gerrit-merge</code>]<br />
<br/><br />
([http://schacon.github.com/git/git-push.html <code>push</code>] to [[Git/Workflow/Stage|topic stage]] and<br />
<br/><br />
<code>stage ITK merge ''my-topic''</code>)<br />
<br/><br />
[[Git/Workflow/Topic/Conflicts#Branch-to-Topic|Branch-to-Topic Conflict Resolution]]<br />
|}<br />
<br />
==Delete a Topic==<br />
<br />
After a topic has been merged upstream, delete your local branch for the topic.<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Checkout and update the '''master''' branch:<br />
|-<br />
|<br />
:<code>$ git checkout master</code><br />
:<code>$ git pullall</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
<br/><br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.pullall</code>]<br />
<br/><br />
([http://schacon.github.com/git/git-pull.html <code>pull</code>] and<br />
[http://schacon.github.com/git/git-submodule.html <code>submodule</code>] <code>update</code>)<br />
|-<br />
|<br />
Delete the local topic branch:<br />
|-<br />
|<br />
:<code>$ git branch -d ''my-topic''</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-branch.html <code>git help branch</code>]<br />
|-<br />
|<br />
The <code>branch -d</code> command works only when the topic branch has been correctly merged.<br />
Use <code>-D</code> instead of <code>-d</code> to force the deletion of an unmerged topic branch<br />
(warning - you could lose commits).<br />
|}</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK/Git/Develop&diff=52035ITK/Git/Develop2013-03-28T18:15:37Z<p>Xiaoxiao: /* Merge a Topic */</p>
<hr />
<div>__NOTOC__<br />
<br />
This page documents how to develop ITK through [http://git-scm.com Git].<br />
See our [[ITK/Git|table of contents]] for more information.<br />
<br />
<i><br />
Git is an extremely powerful version control tool that supports many different "workflows" for indivudal development and collaboration.<br />
Here we document procedures used by the ITK development community.<br />
In the interest of simplicity and brevity we do '''not''' provide an explanation of why we use this approach.<br />
Furthermore, this is '''not''' a Git tutorial.<br />
Please see our [[Git/Resources|Git resource links]] for third-party documentation, such as the [http://git-scm.com/book/ ProGit Book].<br />
</i><br />
<br />
==Setup==<br />
<br />
Before you begin, perform initial setup:<br />
<br />
{| style="width: 100%" cellspacing="0" cellpadding="0"<br />
|-<br />
|width=60%|<br />
1.<br />
Register [[ITK/Git/Account#Gerrit|Gerrit access]] and possibly [[ITK/Git/Account#Git|Git push access]].<br />
|-<br />
|<br />
2.<br />
Optionally download our [[Media:GitITKCheatSheet.pdf|one page PDF desk reference]].<br />
|-<br />
|<br />
3.<br />
Follow the [[ITK/Git/Download#Clone|download instructions]] to create a local ITK clone:<br />
|-<br />
|<br />
:<code>$ git clone git://itk.org/ITK.git</code><br />
|align="center"|<br />
[[Git/Trouble#Firewall_Blocks_Port_9418|Connection refused]]?<br />
|-<br />
|<br />
4.<br />
Run the developer setup script to prepare your ITK work tree and create Git command aliases used below:<br />
|-<br />
|<br />
:<code>$ ./Utilities/SetupForDevelopment.sh</code><br />
|align="center"|<br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/SetupForDevelopment.sh;hb=HEAD <code>SetupForDevelopment.sh</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Getting-Started-First-Time-Git-Setup Pro Git: Setup]<br />
|}<br />
<br />
==Workflow==<br />
<br />
ITK development uses a [[Git/Workflow/Topic|branchy workflow]] based on topic branches.<br />
Our collaboration workflow consists of three main steps:<br />
<br />
{| style="width: 100%" cellspacing="0" cellpadding="0"<br />
|-<br />
|width=60%|<br />
1.<br />
Local Development<br />
|-<br />
|<br />
:* [[#Update|Update]]<br />
|-<br />
|<br />
:* [[#Create_a_Topic|Create a Topic]]<br />
|-<br />
|<br />
2.<br />
Code Review<br />
|-<br />
|<br />
:* [[#Share_a_Topic|Share a Topic]] (requires [[ITK/Git/Account#Gerrit|Gerrit access]])<br />
|align="center"|<br />
[http://code.google.com/p/gerrit/ Gerrit Code Review]<br />
|-<br />
|<br />
:* [[#Revise_a_Topic|Revise a Topic]]<br />
|-<br />
|<br />
3.<br />
Integrate Changes<br />
|-<br />
|<br />
:* [[#Merge_a_Topic|Merge a Topic]] (requires [[ITK/Git/Account#Git|Git push access]])<br />
|-<br />
|<br />
:* [[#Delete_a_Topic|Delete a Topic]]<br />
|}<br />
<br />
==Update==<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Update your local '''master''' branch:<br />
|-<br />
|<br />
:<code>$ git checkout master</code><br />
:<code>$ git pullall</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
<br/><br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.pullall</code>]<br />
<br/><br />
([http://schacon.github.com/git/git-pull.html <code>pull</code>] and<br />
[http://schacon.github.com/git/git-submodule.html <code>submodule</code>] <code>update</code>)<br />
|}<br />
<br />
==Create a Topic==<br />
<br />
All new work must be committed on topic branches.<br />
Name topics like you might name functions: concise but precise.<br />
A reader should have a general idea of the feature or fix to be developed given just the branch name.<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
To start a new topic branch:<br />
|-<br />
|<br />
:<code>$ git fetch origin</code><br />
:{|<br />
|-<br />
|<br />
For new development, start the topic from <code>origin/master</code>:<br />
:<code>$ git checkout -b ''my-topic'' origin/master</code><br />
|-<br />
|<br />
For release branch fixes, start the topic from <code>origin/release</code>, and by convention use a topic name starting in "<code>release-</code>":<br />
:<code>$ git checkout -b ''my-topic'' origin/release</code><br />
|}<br />
|align="center"|<br />
[http://schacon.github.com/git/git-fetch.html <code>git help fetch</code>]<br />
<br/><br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
<br/><br />
[http://schacon.github.com/git/git-submodule.html <code>git help submodule</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging Pro Git: Basic Branching]<br />
|-<br />
|<br />
Edit files and create commits (repeat as needed):<br />
|-<br />
|<br />
:<code>$ edit ''file1'' ''file2'' ''file3''</code><br />
:''(To add data follow [[ITK/Git/Develop/Data#Add_Data|these instructions]].)''<br />
:<code>$ git add ''file1'' ''file2'' ''file3''</code><br />
:<code>$ git commit</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-add.html <code>git help add</code>]<br />
<br/><br />
[http://schacon.github.com/git/git-commit.html <code>git help commit</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Basics-Recording-Changes-to-the-Repository Pro Git: Recording Changes]<br />
|-<br />
|<br />
''(If your change modifies the "<code>Modules/ThirdParty/KWSys/src/KWSys</code>" directory please contribute directly to [[KWSys/Git|KWSys]] instead.)''<br />
|}<br />
<br />
==Share a Topic==<br />
<br />
When a topic is ready for review and possible inclusion, share it by pushing to Gerrit.<br />
Be sure you have registered for [[ITK/Git/Account#Gerrit|Gerrit access]].<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Checkout the topic if it is not your current branch:<br />
|-<br />
|<br />
:<code>$ git checkout ''my-topic''</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
|-<br />
|<br />
Check what commits will be pushed to Gerrit for review:<br />
|-<br />
|<br />
:<code>$ git prepush</code><br />
or if you started the topic from the release branch:<br />
:<code>$ git push gerrit HEAD:refs/for/release/my-topic </code> <br />
|align="center"|<br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.prepush</code>]<br />
<br/><br />
([http://schacon.github.com/git/git-log.html <code>log</code>] <code>origin/master..</code>)<br />
|-<br />
|<br />
Push commits in your topic branch for review by the community:<br />
|-<br />
|<br />
:<code>$ git gerrit-push</code><br />
:''(If the topic adds data see [[ITK/Git/Develop/Data#Push|this note]].)''<br />
|align="center"|<br />
[[ITK/Git/Account#Firewall_blocks_SSH_traffic|Connection refused]]?<br />
<br/><br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.gerrit-push</code>]<br />
<br/><br />
([http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/Git/git-gerrit-push;hb=HEAD <code>Utilities/Git/git-gerrit-push</code>])<br />
|}<br />
Find your change in the [http://review.source.kitware.com/p/ITK ITK Gerrit] instance and add [[ITK/Gerrit/Reviewers|reviewers]].<br />
<br />
==Revise a Topic==<br />
<br />
If a topic is approved during Gerrit review, skip to the [[#Merge_a_Topic|next step]].<br />
Otherwise, revise the topic and push it back to Gerrit for another review.<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Checkout the topic if it is not your current branch:<br />
|-<br />
|<br />
:<code>$ git checkout ''my-topic''</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
|-<br />
|<br />
To revise the most recent commit on the topic edit files and add changes normally and then amend the commit:<br />
|-<br />
|<br />
:<code>$ git commit --amend</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-commit.html <code>git help commit</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Tools-Rewriting-History#Changing-the-Last-Commit Pro Git: Changing the Last Commit]<br />
|-<br />
|<br />
To revise commits further back on the topic, say the <code>3</code>rd commit back:<br />
|-<br />
|<br />
:<code>$ git rebase -i HEAD~3</code><br />
''(Substitute the correct number of commits back, as low as ''<code>1</code>''.)''<br />
<br />
Follow Git's interactive instructions.<br />
Preserve the <code>Change-Id:</code> line at the bottom of each commit message.<br />
|align="center"|<br />
[http://schacon.github.com/git/git-rebase.html <code>git help rebase</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Tools-Rewriting-History#Changing-Multiple-Commit-Messages Pro Git: Changing Multiple Commits]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Branching-Rebasing Pro Git: Rebasing]<br />
|-<br />
|<br />
Return to the [[#Share_a_Topic|previous step]] to share the revised topic.<br />
|}<br />
<br />
==Merge a Topic==<br />
<br />
After a feature topic has been reviewed and approved in Gerrit, merge it into the upstream repository.<br />
'''Only authorized developers with [[ITK/Git/Account#Git|Git push access]] to <code>itk.org</code> may perform this step.'''<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Checkout the topic if it is not your current branch:<br />
|-<br />
|<br />
:<code>$ git checkout ''my-topic''</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
|-<br />
|<br />
Merge the topic, which is originally forked off the master branch, to master branch:<br />
|-<br />
|<br />
:<code>$ git gerrit-merge</code><br />
<br />
For bug fixes that are ready to be included in the next release, please email the release manager<br />
Matt Mccormick([[matt.mccormick@kitware.com)]] for assistance.<br />
Here are the recommended steps to merge a topic to both release and master branches, assuming the topic<br />
branch is forked off the release branch:<br />
|-<br />
|<br />
:<code>$ git checkout release</code><br />
:<code>$ git merge --no-ff my-topic</code><br />
:<code>$ git push origin/release</code><br />
and do:<br />
|-<br />
|<br />
:<code>$ git checkout master</code><br />
:<code>$ git merge --no-ff release</code><br />
:<code>$ git push origin/master</code><br />
to merge the release branch back to master.<br />
<br />
:''(If the merge conflicts follow the printed instructions to resolve them.)''<br />
|align="center"|<br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.gerrit-merge</code>]<br />
<br/><br />
([http://schacon.github.com/git/git-push.html <code>push</code>] to [[Git/Workflow/Stage|topic stage]] and<br />
<br/><br />
<code>stage ITK merge ''my-topic''</code>)<br />
<br/><br />
[[Git/Workflow/Topic/Conflicts#Branch-to-Topic|Branch-to-Topic Conflict Resolution]]<br />
|}<br />
<br />
==Delete a Topic==<br />
<br />
After a topic has been merged upstream, delete your local branch for the topic.<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Checkout and update the '''master''' branch:<br />
|-<br />
|<br />
:<code>$ git checkout master</code><br />
:<code>$ git pullall</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
<br/><br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.pullall</code>]<br />
<br/><br />
([http://schacon.github.com/git/git-pull.html <code>pull</code>] and<br />
[http://schacon.github.com/git/git-submodule.html <code>submodule</code>] <code>update</code>)<br />
|-<br />
|<br />
Delete the local topic branch:<br />
|-<br />
|<br />
:<code>$ git branch -d ''my-topic''</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-branch.html <code>git help branch</code>]<br />
|-<br />
|<br />
The <code>branch -d</code> command works only when the topic branch has been correctly merged.<br />
Use <code>-D</code> instead of <code>-d</code> to force the deletion of an unmerged topic branch<br />
(warning - you could lose commits).<br />
|}</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=Git/Workflow/Topic&diff=52034Git/Workflow/Topic2013-03-28T17:52:21Z<p>Xiaoxiao: /* Published Branches */</p>
<hr />
<div>=Introduction=<br />
<br />
This workflow is based on the branchy development workflow documented by [http://schacon.github.com/git/gitworkflows.html <code>git help workflows</code>].<br />
<br />
==Motivation==<br />
<br />
The primary goal of this workflow is to make release preparation and maintenance easier.<br />
We set the following requirements, of which some are themselves worthwhile goals:<br />
<br />
* Amortize the effort of release preparation throughout development<br />
* Support granular selection of features for release<br />
* Allow immature features to be published without delaying release<br />
* '''Keep unrelated development paths (''topics'') independent of one another'''<br />
* Maintain a clean [[#History_Shape|shape of history]]<br />
<br />
==Design==<br />
<br />
The design of this workflow is based on the observation that meeting the highlighted goal makes the other goals easy.<br />
It is based on branchy development in which each branch has a well-defined purpose.<br />
<br />
We define two branch types:<br />
<br />
* '''Topic Branch'''<br />
** Commits represent ''changes'' (real work)<br />
** Distinguished by ''feature'' (one topic per feature or fix)<br />
** Named locally by each developer (describe purpose of work)<br />
** Heads not published (no named branch on server)<br />
* '''Integration Branch'''<br />
** Commits represent ''merges'' (merge topics together)<br />
** Distinguished by ''stability'' (release maintenance, release preparation, development edge)<br />
** Named everywhere<br />
** Heads published on server<br />
<br />
==Notation==<br />
<br />
This document uses ascii-art to depict commit history:<br />
<br />
{|<br />
|-<br />
|<br />
Branch name<br />
|<br />
master<br />
|-<br />
|<br />
Current branch<br />
|<br />
*'''master'''<br />
|-<br />
|<br />
Commit with parent in same branch<br />
|<br />
----o<br />
|-<br />
|<br />
Commit with parent in another branch<br />
|<br />
\<br />
o<br />
|-<br />
|<br />
Commit with two parents (merge)<br />
|<br />
----o<br />
/<br />
|-<br />
|<br />
Commit with arbitrary ancestry<br />
|<br />
...o<br />
|}<br />
<br />
Topic branches generally consist of a linear sequence of commits forked off an integration branch:<br />
<br />
...o master<br />
\<br />
o----o----o----o ''topic''<br />
<br />
Integration branches generally consist of a sequence of merge commits:<br />
<br />
...o ...o<br />
\ \<br />
...o----o----o----o----o master<br />
/ /<br />
...o ...o<br />
<br />
==Published Branches==<br />
<br />
We publish an ''integration'' branch for each stage of development:<br />
<br />
* '''main''': Release maintenance (high stability). Only bug fixes should be published here. Only the release manager can push here.<br />
* '''master''': Release preparation (medium stability). Only mature features and bug fixes should be published here.<br />
* '''next''': Development (low stability). New features should be published here.<br />
<br />
Topic branches are not published directly; their names exist only in each developer's local repositories.<br />
<br />
=Development=<br />
<br />
We cover below the steps to take during each phase of development.<br />
<br />
==Initial Setup==<br />
<br />
These instructions generally provide all arguments to "<code>git push</code>" commands.<br />
Some people prefer to use "<code>git push</code>" with no additional arguments to push the current tracking branch.<br />
Run the command<br />
<br />
$ git config --global push.default tracking<br />
<br />
to establish this behavior.<br />
See the [http://schacon.github.com/git/git-config.html git config] man-page for details.<br />
<br />
==New Topic==<br />
<br />
Create a new topic branch for each separate feature or bug fix.<br />
Always start the topic from a stable integration branch, usually '''master'''.<br />
If the topic fixes a bug in the current release, use '''maint'''.<br />
''Never'' start a topic from '''next'''!<br />
In the following table we review the steps and commands to create,<br />
develop, and publish a ''topic'' branch based on '''master'''.<br />
<br />
{| style="width: 100%" cellspacing="0" cellpadding="0"<br />
!width=30%|Actions<br />
!width=30%|Results<br />
!Troubleshooting<br />
|-<br />
|colspan="2"|<br />
Update '''master''' to base work on the most recently integrated features.<br />
|-<br />
|<br />
:<code>$ git checkout master</code><br />
|<br />
...o *'''master'''<br />
|-<br />
|<br />
:<code>$ git pull</code><br />
|<br />
...o----o *'''master'''<br />
|-<br />
|colspan="2"|<br />
Create the local ''topic'' branch. [[#Naming_Topics|'''Use a meaningful name for''' "'''''topic'''''"]].<br />
|-<br />
|<br />
:<code>$ git checkout -b ''topic''</code><br />
|<br />
...o----o master<br />
^ *'''''topic'''''<br />
|-<br />
|colspan="2"|<br />
This is where the real work happens.<br />
Edit, stage, and commit files repeatedly as needed for your work.<br />
<br />
During this step, [[#Urge_to_Merge|'''avoid the "urge to merge"''']] from an integration branch.<br />
Keep your commits focused on the topic at hand.<br />
|-<br />
|<br />
:<code>$ edit ''files''</code><br><br />
:<code>$ git add -- ''files''</code><br><br />
:<code>$ git commit</code><br />
|<br />
...o----o master<br />
\<br />
o *'''''topic'''''<br />
|-<br />
|<br />
:<code>$ edit ''files''</code><br><br />
:<code>$ git add -- ''files''</code><br><br />
:<code>$ git commit</code><br />
|<br />
...o----o master<br />
\<br />
o----o *'''''topic'''''<br />
|-<br />
|colspan="2"|<br />
When the topic is ready for publication it must be merged into '''next'''.<br />
Do ''not'' merge ''from'' '''next'''!<br />
It should be the current local branch when you merge.<br />
<br />
Switch to '''next''' and update it.<br />
Use "<code>git checkout -b next origin/next</code>" to create a local '''next''' the first time.<br />
|-<br />
|<br />
:<code>$ git checkout next</code><br><br />
:<code>$ git pull</code><br />
|<br />
...o----o master<br />
. \<br />
. o----o ''topic''<br />
.<br />
........o *'''next'''<br />
|-<br />
|colspan="2"|<br />
Merge the ''topic'' and test it.<br />
|-<br />
|<br />
:<code>$ git merge ''topic''</code><br />
|<br />
...o----o master<br />
. \<br />
. o----o ''topic''<br />
. \<br />
........o----o *'''next'''<br />
|align="center"|<br />
[[Git/Workflow/Topic/Conflicts#Multiple_Integration_Branches|conflicts?]]<br />
|-<br />
|colspan="2"|<br />
Finally, publish the change.<br />
|-<br />
|<br />
:<code>$ git push origin next</code><br />
|<br />
...o----o master<br />
. \<br />
. o----o ''topic''<br />
. \<br />
........o----o *'''next''' (and origin/next)<br />
|align="center"|<br />
[[#remote_end_hung_up_unexpectedly|remote end hung up unexpectedly]]?<br />
<br />
[[#non-fast-forward|non-fast-forward]]?<br />
|}<br />
<br />
==Mature Topic==<br />
<br />
When a topic is ready for inclusion in the next release, we merge it into '''master'''.<br />
<br />
{| style="width: 100%" cellspacing="0" cellpadding="0"<br />
!width=30%|Actions<br />
!width=30%|Results<br />
!Troubleshooting<br />
|-<br />
|colspan=2|<br />
Update '''master''' to get the latest work by others.<br />
We will merge the topic into it.<br />
|-<br />
|<br />
:<code>$ git checkout master</code><br />
|<br />
...o----o *'''master'''<br />
. \<br />
. o----o ''topic''<br />
. \<br />
........o----o next<br />
|-<br />
|<br />
:<code>$ git pull</code><br />
|<br />
..........<br />
. \<br />
...o----o----o *'''master'''<br />
. \<br />
. o----o ''topic''<br />
. \<br />
........o----o next<br />
|-<br />
|colspan=2|<br />
Merge the ''topic'' and test it.<br />
|-<br />
|<br />
:<code>$ git merge ''topic''</code><br />
|<br />
..........<br />
. \<br />
...o----o----o---o *'''master'''<br />
. \ /<br />
. o----o ''topic''<br />
. \<br />
........o----o next<br />
|align="center"|<br />
[[Git/Workflow/Topic/Conflicts#Multiple_Integration_Branches|conflicts?]]<br />
|-<br />
|colspan=2|<br />
Delete the local branch.<br />
|-<br />
|<br />
:<code>$ git branch -d ''topic''</code><br />
|<br />
..........<br />
. \<br />
...o----o----o---o *'''master'''<br />
. \ /<br />
. o----o<br />
. \<br />
........o----o next<br />
|-<br />
|colspan="2"|<br />
Finally, publish the change.<br />
|-<br />
|<br />
:<code>$ git push origin master</code><br />
|<br />
..........<br />
. \<br />
...o----o----o---o *'''master''', origin/master<br />
\ /<br />
o----o<br />
|align="center"|<br />
[[#remote_end_hung_up_unexpectedly|remote end hung up unexpectedly]]?<br />
<br />
[[#non-fast-forward|non-fast-forward]]?<br />
|}<br />
<br />
Note that '''master''' sees only the topics that have been merged into it.<br />
It cannot reach any of the merges into '''next''':<br />
<br />
..........<br />
. \<br />
...o----o----o---o *'''master'''<br />
\ /<br />
o----o (''topic'')<br />
<br />
==Old Topic==<br />
<br />
Sometimes we need to continue work on an old topic that has already been merged to an integration branch and for which we no longer have a local ''topic'' branch.<br />
To revive an old topic, we create a local branch based on the last commit from the topic (this is ''not'' one of the merges into an integration branch).<br />
<br />
First we need to identify the commit by its hash.<br />
It is an ancestor of the integration branch into which it was once merged, say '''next'''.<br />
Run <code>git log</code> with the <code>--first-parent</code> option to view the integration history:<br />
<br />
$ git log --first-parent next<br />
commit 9057863...<br />
Merge: 2948732 a348901<br />
...<br />
Merge branch ''topicA''<br />
<br />
commit 2948732...<br />
Merge: 1094687 b235725<br />
...<br />
Merge branch ''topicB''<br />
<br />
commit 1094687...<br />
Merge: 8267263 c715789<br />
...<br />
Merge branch ''topicC''<br />
<br />
Locate the merge commit for the topic of interest, say ''topicB''.<br />
It's ''second'' parent is the commit from which we will restart work (<code>b235725</code> in this example).<br />
<br />
{| style="width: 100%" cellspacing="0" cellpadding="0"<br />
!width=30%|Actions<br />
!width=30%|Results<br />
!Troubleshooting<br />
|-<br />
|colspan=2|<br />
Create a local ''topic'' branch starting from the commit identified above.<br />
|-<br />
|<br />
:<code>$ git checkout -b ''topic'' b235725</code><br />
|<br />
..........<br />
. \<br />
...o----o----o---o master<br />
. \ /<br />
. o----o *'''''topic''''' (b235725)<br />
. \<br />
........o----o----o next<br />
/ /<br />
...o ...o<br />
(c715789) (a348901)<br />
|-<br />
|colspan=2|<br />
Continue development on the topic.<br />
|-<br />
|<br />
:<code>$ edit ''files''</code><br><br />
:<code>$ git add -- ''files''</code><br><br />
:<code>$ git commit</code><br />
|<br />
..........<br />
. \<br />
...o----o----o---o master<br />
. \ /<br />
. o----o----o *'''''topic'''''<br />
. \<br />
........o----o----o next<br />
/ /<br />
...o ...o<br />
|-<br />
|<br />
:<code>$ edit ''files''</code><br><br />
:<code>$ git add -- ''files''</code><br><br />
:<code>$ git commit</code><br />
|<br />
..........<br />
. \<br />
...o----o----o---o master<br />
. \ /<br />
. o----o----o----o *'''''topic'''''<br />
. \<br />
........o----o----o next<br />
/ /<br />
...o ...o<br />
|-<br />
|colspan=2|<br />
When the new portion of the topic is ready, merge it into '''next''' and test.<br />
|-<br />
|<br />
:<code>$ git checkout next</code><br />
:<code>$ git pull</code><br />
:<code>$ git merge ''topic''</code><br />
|<br />
..........<br />
. \<br />
...o----o----o---o master<br />
. \ /<br />
. o----o----o----o ''topic''<br />
. \ \<br />
........o----o----o----o *'''next'''<br />
/ /<br />
...o ...o<br />
|-<br />
|colspan=2|<br />
Publish '''next'''.<br />
|-<br />
|<br />
:<code>$ git push origin next</code><br />
|-<br />
|colspan=2|<br />
Optionally repeat the above, publishing to next, to continue development based on feedback from initial publication.<br />
Finally, when the new changes are mature, merge to '''master''' and publish.<br />
|-<br />
|<br />
:<code>$ git checkout master</code><br />
:<code>$ git pull</code><br />
:<code>$ git merge ''topic''</code><br />
|<br />
..........<br />
. \<br />
...o----o----o---o---------o *'''master'''<br />
. \ / /<br />
. o----o----o----o topic<br />
. \ \<br />
........o----o----o----o next<br />
/ /<br />
...o ...o<br />
|-<br />
|<br />
:<code>$ git branch -d ''topic''</code><br />
:<code>$ git push origin master</code><br />
|<br />
..........<br />
. \<br />
...o----o----o---o---------o *'''master'''<br />
. \ / /<br />
. o----o----o----o<br />
. \ \<br />
........o----o----o----o next<br />
/ /<br />
...o ...o<br />
|}<br />
<br />
Again, note that '''master''' sees only the topics that have been merged into it.<br />
It cannot reach any of the merges into '''next''':<br />
<br />
..........<br />
. \<br />
...o----o----o---o---------o *'''master'''<br />
\ / /<br />
o----o----o----o (''topic'')<br />
<br />
==Dependent Topic==<br />
<br />
Occasionally you may realize that you need the work from another topic to complete work on your topic.<br />
In this case your topic ''depends'' on the other topic, so merging the other topic into yours is [[#Legitimate_Merges|legitimate]].<br />
''Do not'' merge an integration branch that has the other topic.<br />
Use the instructions below to merge ''only the other topic'' without getting everything else.<br />
<br />
{| style="width: 100%" cellspacing="0" cellpadding="0"<br />
!width=30%|Actions<br />
!width=30%|Results<br />
!Troubleshooting<br />
|-<br />
|colspan="2"|<br />
Fetch the upstream integration branch that has the ''other-topic'' branch, say '''master'''.<br />
|-<br />
|<br />
:<code>$ git fetch origin</code><br />
|<br />
...o (''extra-topic'')<br />
\ \<br />
...o----o-----o----o origin/master<br />
\ \ /^ "Merge branch '<i>other-topic</i>'"<br />
\ o------o 0a398e5<br />
\<br />
o----o *'''''topic'''''<br />
|-<br />
|colspan="2"|<br />
Use <code>git log --first-parent origin/master</code> to find the commit that merges ''other-topic''.<br />
The commit message gives you the name of the other topic branch (we use "''other-topic''" here as a placeholder).<br />
The second parent of the commit (<code>0a398e5</code> in this example) is the end of the ''other-topic'' branch.<br />
Create a local branch from that commit.<br />
|-<br />
|<br />
:<code>$ git branch ''other-topic'' 0a398e5</code><br />
|<br />
...o (''extra-topic'')<br />
\ \<br />
...o----o-----o----o origin/master<br />
\ \ /<br />
\ o------o ''other-topic''<br />
\<br />
o----o *'''''topic'''''<br />
|-<br />
|colspan="2"|<br />
Merge the other branch into your topic.<br />
|-<br />
|<br />
:<code>$ git merge ''other-topic''</code><br />
:<code>$ git branch -d ''other-topic''</code><br />
|<br />
...o (''extra-topic'')<br />
\ \<br />
...o----o-----o----o origin/master<br />
\ \ /<br />
\ o------o<br />
\ \<br />
o----o------o *'''''topic'''''<br />
^ "Merge branch '<i>other-topic</i>' into ''topic''"<br />
|}<br />
(It is also possible to run <code>git merge 0a398e5</code> and then use <code>git commit --amend</code> to write a nice commit message.)<br />
<br />
The ''topic'' branch now looks like this:<br />
<br />
\<br />
...o----o<br />
\ \<br />
\ o------o (''other-topic'')<br />
\ \<br />
o----o------o *'''''topic'''''<br />
<br />
Note that after the merge, the ''other-topic'' is reachable from your ''topic'' but the ''extra-topic'' has not been included.<br />
By not merging from the integration branch we avoided bringing in an unnecessary dependency on the ''extra-topic''.<br />
Furthermore, the message "<code>Merge branch '<i>other-topic</i>' into ''topic''</code>" is very informative about the purpose of the merge.<br />
Merging the whole integration branch would not be so clear.<br />
<br />
==Merge Integration Branches==<br />
<br />
Each [[#Published_Branches|published integration branch]] has a defined level of stability.<br />
Express this relationship by merging more-stable branches into less-stable branches to ensure that they do not diverge.<br />
After merging a mature topic to '''master''', we merge '''master''' into '''next''':<br />
<br />
{| style="width: 100%" cellspacing="0" cellpadding="0"<br />
!width=30%|Actions<br />
!width=30%|Results<br />
!Troubleshooting<br />
|-<br />
|colspan=2|<br />
Update '''master''' and then '''next''':<br />
|-<br />
|<br />
:<code>$ git checkout master</code><br />
:<code>$ git pull</code><br />
:<code>$ git checkout next</code><br />
:<code>$ git pull</code><br />
|<br />
..........<br />
. \<br />
...o----o----o---o master<br />
. \ /<br />
. o----o<br />
. \<br />
........o----o *'''next'''<br />
|-<br />
|colspan=2|<br />
Merge '''master''' into '''next''':<br />
|-<br />
|<br />
:<code>$ git merge master</code><br />
|<br />
..........<br />
. \<br />
...o----o----o---o master<br />
. \ / \<br />
. o----o \<br />
. \ \<br />
........o----o---o *'''next'''<br />
|-<br />
|colspan="2"|<br />
Finally, publish the change.<br />
|-<br />
|<br />
:<code>$ git push origin next</code><br />
|<br />
..........<br />
. \<br />
...o----o----o---o master, origin/master<br />
. \ / \<br />
. o----o \<br />
. \ \<br />
........o----o---o *'''next''', origin/next<br />
|align="center"|<br />
[[#remote_end_hung_up_unexpectedly|remote end hung up unexpectedly]]?<br />
<br />
[[#non-fast-forward|non-fast-forward]]?<br />
|}<br />
<br />
=Discussion=<br />
<br />
==History Shape==<br />
<br />
The history graphs produced by this workflow may look complex compared to the fully linear history produced by a rebase workflow (used by CVS and Subversion):<br />
<br />
..........<br />
. \<br />
...o----o----o---o---------o master<br />
. \ / /<br />
. o----o----o----o topic<br />
. \ \<br />
........o----o----o----o next<br />
/ /<br />
...o ...o<br />
<br />
However, consider the shape of history along each branch.<br />
We can view it using Git's <code>--first-parent</code> option.<br />
It traverses history by following only the ''first parent'' of each merge.<br />
The first parent is the commit that was currently checked out when the <code>git merge</code> command was invoked to create the merge commit.<br />
By following only the first parent, we see commits that logically belong to a specific branch.<br />
<br />
{| style="width: 100%" cellspacing="0" cellpadding="0"<br />
!width=30%|Command<br />
!width=30%|View<br />
!<br />
|-<br />
|<br />
:<code>$ git log --first-parent ''topic''</code><br />
|<br />
...<br />
\<br />
o----o----o----o topic<br />
|-<br />
|<br />
:<code>$ git log --first-parent master</code><br />
|<br />
\<br />
...o----o----o---o---------o master<br />
/ /<br />
|-<br />
|<br />
:<code>$ git log --first-parent next</code><br />
|<br />
\ \<br />
...o----o----o----o next<br />
/ /<br />
|}<br />
<br />
Each branch by itself looks linear and has only commits with a specific purpose.<br />
The history behind each commit is unique to that purpose.<br />
Topic branches are independent, containing only commits for their specific feature or fix.<br />
Integration branches consist of merge commits that integrate topics together.<br />
<br />
Note that achieving the nice separation of branches requires understanding of the above development procedure and strict adherence to it.<br />
<br />
==Naming Topics==<br />
<br />
This document uses the italicized placeholder "''topic''" in place of a real topic name.<br />
In practice, substitute a meaningful name.<br />
Name topics like you might name functions: concise but precise.<br />
A reader should have a general idea of the feature or fix to be developed given just the branch name.<br />
<br />
Note that topic names are not published as branch heads on the server, so no one will ever see a branch by your topic name unless they create it themselves.<br />
However, the names ''do'' appear in the default merge commit message:<br />
<br />
$ git checkout next<br />
$ git merge ''topic''<br />
$ git show<br />
...<br />
Merge branch '<i>topic</i>' into next<br />
...<br />
<br />
These merge commits appear on the integration branches and should therefore describe the changes they integrate.<br />
Running <code>git log --first-parent</code> as described [[#History_Shape|here]] will show only these merge commits, so their messages should be descriptive of the changes made on their topics.<br />
If you did not choose a good branch name, or feel that the merge needs more explanation than the branch name provides, amend the commit to update the message by hand:<br />
<br />
$ git commit --amend<br />
Merge branch '<i>topic</i>' into next<br />
''(edit the message)''<br />
<br />
==Urge to Merge==<br />
<br />
Avoid the "urge to merge" from an integration branch into your topic.<br />
Keep commits on your topic focused on the feature or fix under development.<br />
<br />
===Habitual Merges===<br />
<br />
Merge your work with others when you are finished with it by merging ''into'' an integration branch as documented above.<br />
Avoid habitual merges ''from'' an integration branch; doing so introduces unnecessary dependencies and complicates the [[#History_Shape|shape of history]].<br />
<br />
Many developers coming from centralized version control systems have trained themselves to regularly update their work tree from the central repository (e.g. "<code>cvs update</code>").<br />
With those version control systems this was a good habit because they did not allow you to commit without first integrating your work with the latest from the server.<br />
When integrating the local and remote changes resulted in conflicts, developers were forced to resolve the conflicts before they could commit.<br />
A mistake during conflict resolution could result in loss of work because the local changes might have been lost.<br />
By regularly updating from the server, developers hoped to avoid this loss of work by resolving conflicts incrementally.<br />
<br />
Developers using Git do not face this problem.<br />
Instead, one should follow a simple motto: "commit first, integrate later".<br />
There is no risk that your work will be lost during conflict resolution because all your changes have been safely committed ''before'' attempting to merge.<br />
If you make a mistake while merging, you always have the option to throw away the merge attempt and start over with a clean tree.<br />
<br />
===Legitimate Merges===<br />
<br />
One reason to merge other work ''into'' your topic is when you realize that your topic depends on it.<br />
See [[#Dependent_Topic|above]] for help with this case.<br />
<br />
Occasionally one may merge directly from '''master''' if there is a good reason.<br />
This is rare, so bring up the reason on your project mailing list first.<br />
''Never merge '''next''' into a topic under any circumstances!!!''<br />
<br />
=Troubleshooting=<br />
<br />
Here we document problems one might encounter while following the workflow instructions above.<br />
This is ''not'' a general Git troubleshooting page.<br />
<br />
==Trouble Merging==<br />
<br />
''TODO: Write this sub-section and link sub-sub-sections from <code>git merge</code> commands above.''<br />
<br />
==Trouble Pushing==<br />
<br />
===remote end hung up unexpectedly===<br />
<br />
Pushing may fail with this error:<br />
<br />
$ git push<br />
fatal: The remote end hung up unexpectedly<br />
<br />
This likely means that you have set a ''push URL'' for the remote repository.<br />
You can see the URL to which it tries to push using <code>-v</code>:<br />
<br />
$ git push -v<br />
Pushing to ''git://public.kitware.com/Project.git''<br />
fatal: The remote end hung up unexpectedly<br />
<br />
The <code>git://</code> repository URL may not be used for pushing; it is meant for efficient read-only anonymous access only.<br />
Instead you need to configure a ssh-protocol URL for pushing:<br />
<br />
$ git config remote.origin.pushurl ''git@public.kitware.com:Project.git''<br />
<br />
(Note that 'pushurl' requires Git >= 1.6.4. Use just 'url' for Git < 1.6.4.) <br />
The URL in the above example is a placeholder.<br />
In practice, '''use the push URL documented for your repository'''.<br />
<br />
The above assumes that you want to push to the same repository that you originally cloned.<br />
To push elsewhere, see help for [http://schacon.github.com/git/git-push.html git push] and [http://schacon.github.com/git/git-remote.html git remote].<br />
<br />
===non-fast-forward===<br />
<br />
When trying to publish new merge commits on an integration branch, perhaps '''next''', the final push may fail:<br />
<br />
$ git push origin next<br />
To ...<br />
! [rejected] next -> next (non-fast-forward)<br />
error: failed to push some refs to '...'<br />
To prevent you from losing history, non-fast-forward updates were rejected<br />
Merge the remote changes before pushing again. See the 'Note about<br />
fast-forwards' section of 'git push --help' for details.<br />
<br />
This means that the server's '''next''' refers to a commit that is not reachable from the '''next''' you are trying to push:<br />
<br />
...o----o master<br />
. \<br />
. o----o topic<br />
. \<br />
. .----o *'''next'''<br />
. .<br />
....o----o origin/next<br />
/<br />
...o (''other-topic'')<br />
<br />
This is the Git equivalent to when <code>cvs commit</code> complains that your file is not up-to-date, but now it applies to the whole project and not just one file.<br />
Git is telling you that it cannot update '''next''' on the server to point at your merge commit because that would throw away someone else's work (such as ''other-topic'').<br />
There are a few possible causes, all of which mean you have not yet integrated your work with the latest from upstream:<br />
<br />
* You forgot to run <code>git pull</code> before <code>git merge</code> so you didn't have everything from upstream<br />
* Someone else managed to merge and push something into '''next''' since you last ran <code>git pull</code><br />
<br />
''Some Git guides may tell you to just <code>git pull</code> again to merge upstream work into yours.''<br />
''That approach is '''not compatible''' with the goals of this workflow.''<br />
We want to preserve a clean [[#History_Shape|shape of history]].<br />
<br />
The solution is to throw away your previous merge and try again, but this time start from the latest upstream work:<br />
<br />
{| style="width: 100%" cellspacing="0" cellpadding="0"<br />
!width=30%|Actions<br />
!width=30%|Results<br />
!<br />
|-<br />
|<br />
:<code>$ git reset --hard origin/next</code><br />
|<br />
...o----o master<br />
. \<br />
. o----o topic<br />
.<br />
...o----o *'''next''', origin/next<br />
/<br />
...o (''other-topic'')<br />
|-<br />
|<br />
:<code>$ git merge topic</code><br />
|<br />
...o----o master<br />
. \<br />
. o----o topic<br />
. \<br />
...o----o----o *'''next'''<br />
/<br />
...o (''other-topic'')<br />
|-<br />
|colspan="2"|<br />
Now your '''next''' can reach the upstream work as well as yours.<br />
Publish it.<br />
|-<br />
|<br />
:<code>$ git push origin next</code><br />
|<br />
...o----o master<br />
. \<br />
. o----o topic<br />
. \<br />
...o----o----o *'''next''', origin/next<br />
/<br />
...o (''other-topic'')<br />
|}<br />
<br />
See [http://schacon.github.com/git/git-rerere.html git rerere] to help avoid resolving the same conflicts on each merge attempt.<br />
<br />
===first-parent sequence not preserved===<br />
<br />
One goal of this workflow is to preserve a clean [[#History_Shape|shape of history]].<br />
This means that a <code>--first-parent</code> traversal of an integration branch, such as '''master''', should see only the merge commits that integrate topics into the branch:<br />
<br />
\ \<br />
...o----o----o----o master<br />
/ /<br />
<br />
The commits on the individual topic branches are not included in the traversal.<br />
This provides a medium-level overview of the development of the project.<br />
<br />
We enforce the shape of history on the server's integration branches using an update hook at push-time.<br />
Each update must point its branch at a new commit from which a first-parent traversal reaches the old head of the branch:<br />
<br />
master@{1}<br />
\ \ \v<br />
...o----D----C----B----A----M master<br />
/ / \ /<br />
U-----T (''topic'')<br />
<br />
A first-parent traversal of '''master''' from before the update (<code>master@{1}</code>) sees <code>A B C D</code>:<br />
<br />
\ \ \<br />
...o----D----C----B----A master@{1}<br />
/ /<br />
<br />
A first-parent traversal of '''master''' from after the update sees <code>M A B C D</code>:<br />
<br />
\ \ \<br />
...o----D----C----B----A----M master<br />
/ / /<br />
<br />
The above assumes correct history shape.<br />
Now, consider what happens if merge <code>M</code> is incorrectly made on the ''topic'' branch:<br />
<br />
master@{1}<br />
\ \ \v<br />
...o----D----C----B---------A<br />
/ / \ \<br />
U----T----M' master<br />
^ (''topic'')<br />
<br />
Now a first-parent traversal of '''master''' from after the update sees <code>M' T U B C D</code>:<br />
<br />
\ \<br />
...o----D----C----B<br />
/ / \ \<br />
U----T----M' master<br />
^ (''topic'')<br />
<br />
This not only shows details of the ''topic'' branch, but skips over <code>A</code> altogether!<br />
Our update hooks will reject the push in this case because the new '''master''' cannot see the old one in a first-parent traversal.<br />
<br />
There are a few possible causes and solutions to the above problem, but all involve non-strict compliance with the workflow instructions.<br />
A likely cause is that you did not create a local ''topic'' branch but instead committed directly on '''master''' and then pulled from upstream before pushing:<br />
<br />
{| style="width: 100%" cellspacing="0" cellpadding="0"<br />
!width=30%|(Wrong) Actions<br />
!width=30%|Results<br />
!<br />
|-<br />
|<br />
:<code>wrong$ git checkout master</code><br />
|<br />
\ \<br />
...o----D----C----B *'''master''', origin/master<br />
/ /<br />
|-<br />
|<br />
:<code>wrong$ edit ''files''</code><br />
:<code>wrong$ git add ''files''</code><br />
:<code>wrong$ git commit</code><br />
|<br />
\ \<br />
...o----D----C----B origin/master<br />
/ / \<br />
U *'''master'''<br />
|-<br />
|<br />
:<code>wrong$ edit ''files''</code><br />
:<code>wrong$ git add ''files''</code><br />
:<code>wrong$ git commit</code><br />
|<br />
\ \<br />
...o----D----C----B origin/master<br />
/ / \<br />
U----T *'''master'''<br />
|-<br />
|<br />
:<code>wrong$ git push origin master</code><br />
|<br />
Rejected as [[#non-fast-forward|non-fast-forward]].<br />
|-<br />
|<br />
:<code>wrong$ git pull</code><br />
|<br />
\ \<br />
...o----D----C----B---------A origin/master<br />
/ / \ \<br />
U----T----M' *'''master'''<br />
|-<br />
|<br />
:<code>wrong$ git push origin master</code><br />
|<br />
Rejected with [[#first-parent_sequence_not_preserved|this error]].<br />
|}<br />
<br />
The solution in this case is to recreate the merge on the proper branch.<br />
<br />
{| style="width: 100%" cellspacing="0" cellpadding="0"<br />
!width=30%|Actions<br />
!width=30%|Results<br />
!<br />
|-<br />
|colspan="2"|<br />
First, create a nicely-named ''topic'' branch starting from the first-parent of the incorrect merge.<br />
|-<br />
|<br />
:<code>$ git branch ''topic'' 'master^1'</code><br />
|<br />
\ \<br />
...o----D----C----B---------A origin/master<br />
/ / \ \<br />
U----T----M' *'''master'''<br />
^ ''topic''<br />
|-<br />
|colspan="2"|<br />
Then reset your local '''master''' to that from upstream.<br />
|-<br />
|<br />
:<code>$ git reset --hard origin/master</code><br />
|<br />
\ \<br />
...o----D----C----B----A *'''master''', origin/master<br />
/ / \<br />
U-----T ''topic''<br />
|-<br />
|colspan="2"|<br />
Now create the correct merge commit as described in the workflow instructions above.<br />
|-<br />
|<br />
:<code>$ git merge ''topic''</code><br />
|<br />
\ \<br />
...o----D----C----B----A----M *'''master'''<br />
/ / \ /<br />
U-----T ''topic''<br />
|-<br />
|<br />
:<code>$ git push origin master</code><br />
:<code>$ git branch -d ''topic''</code><br />
|<br />
\ \<br />
...o----D----C----B----A----M *'''master''', origin/master<br />
/ / \ /<br />
U-----T<br />
|}<br />
<br />
===topics must be merged===<br />
<br />
''TODO''<br />
<br />
Note: I was referred to this documentation when my merge to master failed a pre-commit hook. The fix was to add "--no-ff" arg when merging the topic.</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK/Git/Develop&diff=52031ITK/Git/Develop2013-03-28T16:38:42Z<p>Xiaoxiao: /* Share a Topic */</p>
<hr />
<div>__NOTOC__<br />
<br />
This page documents how to develop ITK through [http://git-scm.com Git].<br />
See our [[ITK/Git|table of contents]] for more information.<br />
<br />
<i><br />
Git is an extremely powerful version control tool that supports many different "workflows" for indivudal development and collaboration.<br />
Here we document procedures used by the ITK development community.<br />
In the interest of simplicity and brevity we do '''not''' provide an explanation of why we use this approach.<br />
Furthermore, this is '''not''' a Git tutorial.<br />
Please see our [[Git/Resources|Git resource links]] for third-party documentation, such as the [http://git-scm.com/book/ ProGit Book].<br />
</i><br />
<br />
==Setup==<br />
<br />
Before you begin, perform initial setup:<br />
<br />
{| style="width: 100%" cellspacing="0" cellpadding="0"<br />
|-<br />
|width=60%|<br />
1.<br />
Register [[ITK/Git/Account#Gerrit|Gerrit access]] and possibly [[ITK/Git/Account#Git|Git push access]].<br />
|-<br />
|<br />
2.<br />
Optionally download our [[Media:GitITKCheatSheet.pdf|one page PDF desk reference]].<br />
|-<br />
|<br />
3.<br />
Follow the [[ITK/Git/Download#Clone|download instructions]] to create a local ITK clone:<br />
|-<br />
|<br />
:<code>$ git clone git://itk.org/ITK.git</code><br />
|align="center"|<br />
[[Git/Trouble#Firewall_Blocks_Port_9418|Connection refused]]?<br />
|-<br />
|<br />
4.<br />
Run the developer setup script to prepare your ITK work tree and create Git command aliases used below:<br />
|-<br />
|<br />
:<code>$ ./Utilities/SetupForDevelopment.sh</code><br />
|align="center"|<br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/SetupForDevelopment.sh;hb=HEAD <code>SetupForDevelopment.sh</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Getting-Started-First-Time-Git-Setup Pro Git: Setup]<br />
|}<br />
<br />
==Workflow==<br />
<br />
ITK development uses a [[Git/Workflow/Topic|branchy workflow]] based on topic branches.<br />
Our collaboration workflow consists of three main steps:<br />
<br />
{| style="width: 100%" cellspacing="0" cellpadding="0"<br />
|-<br />
|width=60%|<br />
1.<br />
Local Development<br />
|-<br />
|<br />
:* [[#Update|Update]]<br />
|-<br />
|<br />
:* [[#Create_a_Topic|Create a Topic]]<br />
|-<br />
|<br />
2.<br />
Code Review<br />
|-<br />
|<br />
:* [[#Share_a_Topic|Share a Topic]] (requires [[ITK/Git/Account#Gerrit|Gerrit access]])<br />
|align="center"|<br />
[http://code.google.com/p/gerrit/ Gerrit Code Review]<br />
|-<br />
|<br />
:* [[#Revise_a_Topic|Revise a Topic]]<br />
|-<br />
|<br />
3.<br />
Integrate Changes<br />
|-<br />
|<br />
:* [[#Merge_a_Topic|Merge a Topic]] (requires [[ITK/Git/Account#Git|Git push access]])<br />
|-<br />
|<br />
:* [[#Delete_a_Topic|Delete a Topic]]<br />
|}<br />
<br />
==Update==<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Update your local '''master''' branch:<br />
|-<br />
|<br />
:<code>$ git checkout master</code><br />
:<code>$ git pullall</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
<br/><br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.pullall</code>]<br />
<br/><br />
([http://schacon.github.com/git/git-pull.html <code>pull</code>] and<br />
[http://schacon.github.com/git/git-submodule.html <code>submodule</code>] <code>update</code>)<br />
|}<br />
<br />
==Create a Topic==<br />
<br />
All new work must be committed on topic branches.<br />
Name topics like you might name functions: concise but precise.<br />
A reader should have a general idea of the feature or fix to be developed given just the branch name.<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
To start a new topic branch:<br />
|-<br />
|<br />
:<code>$ git fetch origin</code><br />
:{|<br />
|-<br />
|<br />
For new development, start the topic from <code>origin/master</code>:<br />
:<code>$ git checkout -b ''my-topic'' origin/master</code><br />
|-<br />
|<br />
For release branch fixes, start the topic from <code>origin/release</code>, and by convention use a topic name starting in "<code>release-</code>":<br />
:<code>$ git checkout -b ''my-topic'' origin/release</code><br />
|}<br />
|align="center"|<br />
[http://schacon.github.com/git/git-fetch.html <code>git help fetch</code>]<br />
<br/><br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
<br/><br />
[http://schacon.github.com/git/git-submodule.html <code>git help submodule</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging Pro Git: Basic Branching]<br />
|-<br />
|<br />
Edit files and create commits (repeat as needed):<br />
|-<br />
|<br />
:<code>$ edit ''file1'' ''file2'' ''file3''</code><br />
:''(To add data follow [[ITK/Git/Develop/Data#Add_Data|these instructions]].)''<br />
:<code>$ git add ''file1'' ''file2'' ''file3''</code><br />
:<code>$ git commit</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-add.html <code>git help add</code>]<br />
<br/><br />
[http://schacon.github.com/git/git-commit.html <code>git help commit</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Basics-Recording-Changes-to-the-Repository Pro Git: Recording Changes]<br />
|-<br />
|<br />
''(If your change modifies the "<code>Modules/ThirdParty/KWSys/src/KWSys</code>" directory please contribute directly to [[KWSys/Git|KWSys]] instead.)''<br />
|}<br />
<br />
==Share a Topic==<br />
<br />
When a topic is ready for review and possible inclusion, share it by pushing to Gerrit.<br />
Be sure you have registered for [[ITK/Git/Account#Gerrit|Gerrit access]].<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Checkout the topic if it is not your current branch:<br />
|-<br />
|<br />
:<code>$ git checkout ''my-topic''</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
|-<br />
|<br />
Check what commits will be pushed to Gerrit for review:<br />
|-<br />
|<br />
:<code>$ git prepush</code><br />
or if you started the topic from the release branch:<br />
:<code>$ git push gerrit HEAD:refs/for/release/my-topic </code> <br />
|align="center"|<br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.prepush</code>]<br />
<br/><br />
([http://schacon.github.com/git/git-log.html <code>log</code>] <code>origin/master..</code>)<br />
|-<br />
|<br />
Push commits in your topic branch for review by the community:<br />
|-<br />
|<br />
:<code>$ git gerrit-push</code><br />
:''(If the topic adds data see [[ITK/Git/Develop/Data#Push|this note]].)''<br />
|align="center"|<br />
[[ITK/Git/Account#Firewall_blocks_SSH_traffic|Connection refused]]?<br />
<br/><br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.gerrit-push</code>]<br />
<br/><br />
([http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/Git/git-gerrit-push;hb=HEAD <code>Utilities/Git/git-gerrit-push</code>])<br />
|}<br />
Find your change in the [http://review.source.kitware.com/p/ITK ITK Gerrit] instance and add [[ITK/Gerrit/Reviewers|reviewers]].<br />
<br />
==Revise a Topic==<br />
<br />
If a topic is approved during Gerrit review, skip to the [[#Merge_a_Topic|next step]].<br />
Otherwise, revise the topic and push it back to Gerrit for another review.<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Checkout the topic if it is not your current branch:<br />
|-<br />
|<br />
:<code>$ git checkout ''my-topic''</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
|-<br />
|<br />
To revise the most recent commit on the topic edit files and add changes normally and then amend the commit:<br />
|-<br />
|<br />
:<code>$ git commit --amend</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-commit.html <code>git help commit</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Tools-Rewriting-History#Changing-the-Last-Commit Pro Git: Changing the Last Commit]<br />
|-<br />
|<br />
To revise commits further back on the topic, say the <code>3</code>rd commit back:<br />
|-<br />
|<br />
:<code>$ git rebase -i HEAD~3</code><br />
''(Substitute the correct number of commits back, as low as ''<code>1</code>''.)''<br />
<br />
Follow Git's interactive instructions.<br />
Preserve the <code>Change-Id:</code> line at the bottom of each commit message.<br />
|align="center"|<br />
[http://schacon.github.com/git/git-rebase.html <code>git help rebase</code>]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Tools-Rewriting-History#Changing-Multiple-Commit-Messages Pro Git: Changing Multiple Commits]<br />
<br/><br />
[http://git-scm.com/book/en/Git-Branching-Rebasing Pro Git: Rebasing]<br />
|-<br />
|<br />
Return to the [[#Share_a_Topic|previous step]] to share the revised topic.<br />
|}<br />
<br />
==Merge a Topic==<br />
<br />
After a topic has been reviewed and approved in Gerrit, merge it into the upstream repository.<br />
'''Only authorized developers with [[ITK/Git/Account#Git|Git push access]] to <code>itk.org</code> may perform this step.'''<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Checkout the topic if it is not your current branch:<br />
|-<br />
|<br />
:<code>$ git checkout ''my-topic''</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
|-<br />
|<br />
Merge the topic:<br />
|-<br />
|<br />
:<code>$ git gerrit-merge</code><br />
:''(If the merge conflicts follow the printed instructions to resolve them.)''<br />
|align="center"|<br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.gerrit-merge</code>]<br />
<br/><br />
([http://schacon.github.com/git/git-push.html <code>push</code>] to [[Git/Workflow/Stage|topic stage]] and<br />
<br/><br />
<code>stage ITK merge ''my-topic''</code>)<br />
<br/><br />
[[Git/Workflow/Topic/Conflicts#Branch-to-Topic|Branch-to-Topic Conflict Resolution]]<br />
|}<br />
<br />
==Delete a Topic==<br />
<br />
After a topic has been merged upstream, delete your local branch for the topic.<br />
<br />
{| style="width: 100%"<br />
|-<br />
|width=60%|<br />
Checkout and update the '''master''' branch:<br />
|-<br />
|<br />
:<code>$ git checkout master</code><br />
:<code>$ git pullall</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]<br />
<br/><br />
[http://itk.org/gitweb?p=ITK.git;a=blob;f=Utilities/DevelopmentSetupScripts/SetupGitAliases.sh;hb=HEAD <code>alias.pullall</code>]<br />
<br/><br />
([http://schacon.github.com/git/git-pull.html <code>pull</code>] and<br />
[http://schacon.github.com/git/git-submodule.html <code>submodule</code>] <code>update</code>)<br />
|-<br />
|<br />
Delete the local topic branch:<br />
|-<br />
|<br />
:<code>$ git branch -d ''my-topic''</code><br />
|align="center"|<br />
[http://schacon.github.com/git/git-branch.html <code>git help branch</code>]<br />
|-<br />
|<br />
The <code>branch -d</code> command works only when the topic branch has been correctly merged.<br />
Use <code>-D</code> instead of <code>-d</code> to force the deletion of an unmerged topic branch<br />
(warning - you could lose commits).<br />
|}</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK/Release_4/Modularization/Add_an_external_module_(external_module)&diff=48937ITK/Release 4/Modularization/Add an external module (external module)2012-10-12T15:19:48Z<p>Xiaoxiao: </p>
<hr />
<div>=== Synopsis ===<br />
<br />
An External Module is distributed outside the ITK main repository, but it could be built into ITK as a module once downloaded into the local copy of ITK source tree.<br />
<br />
=== Organization ===<br />
<br />
The organization of an External Module should be the same as an Internal Module: <br />
[[ITK_Release_4/Modularization/ Add a module|Add a module (Internal Module)]]<br />
<br />
To build an External Module, users download it into a local copy of ITK source tree under: ''ITK/Modules/External/''. Then simply rerun the CMake step to configure the new External Module together with other enabled ITK modules.<br />
<br />
<br />
==== External Module Template ====<br />
<br />
Here is a module template for your convenience to build your own module (thanks to Bradley Lowekamp), along with instructions:<br />
* https://github.com/blowekamp/itkExternalTemplate<br />
<br />
<br />
==== Testing data ====<br />
<br />
Testing data, such an input and baseline images, are typically kept outside of the Git repository to keep the repository small.<br />
<br />
The ITK method for handling test data is the [[ITK/Git/Develop/Data#ExternalData | CMake/ExternalData]] method, where MD5 hashes of the data are stored in the repository, then the files corresponding to the hashes are fetched at build time from a list of data servers. These data servers can be an Apache server you have at your webhost, a [http://midasplatform.org/ Midas server], a Dropbox account, an Amazon S3 account, a Rackspace Cloud File account, etc.<br />
<br />
To use the ExternalData mechanism with your own data server:<br />
<br />
# Add testing data references in you ''test/CMakeLists.txt'' as you normally would, i.e. use '''itk_add_test''' and with '''DATA{Baseline/image.mha}'''.<br />
# As usual, copy the image to its location specifie within ''DATA{}''.<br />
# As usual, next time ''cmake'' is executed, a message will appear like: ''Linked Modules/External/ITKMyNewModule/test/Baseline/image.mha.md5 to ExternalData MD5/a3519cb25bb2afeda999378a2f8103cc''<br />
# Copy the file ''test/Baseline/.ExternalData_MD5_a3519cb25bb2afeda999378a2f8103cc'' to a location on your publically available data server, such as ''http://www.example.com/ITKExternalData/MD5/a3519cb25bb2afeda999378a2f8103cc''.<br />
# In your ITK CMake configuration, set the value of ''ExternalData_URL_TEMPLATES'' to ''http://www.example.com/ITKExternalData/%(algo)/%(hash)''<br />
<br />
=== Community dissemination ===<br />
<br />
An example is demonstrated in the Lesion Sizing Toolkit: [http://public.kitware.com/LesionSizingKit/index.php/Users/Build_LST_as_ITK_module Lesion Sizing Toolkit Wiki]<br />
<br />
Once you have your External Module, you can make it available as a [[ITK/Policy_and_Procedures_for_Adding_Remote_Modules| Remote Module]] so it has broader exposure to the ITK community.</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK_Release_4/Video&diff=46646ITK Release 4/Video2012-04-22T03:04:28Z<p>Xiaoxiao: </p>
<hr />
<div>Video<br />
<br />
= Overview =<br />
<br />
A range of applications are based on analyzing temporal data<br />
<br />
* Ultrasound<br />
* Image guidance<br />
* Longitudinal studies<br />
* Perfusion<br />
* Functional MRI<br />
* Laparoscopy<br />
* 4D Microscopy<br />
* Remote Sensing<br />
<br />
= Technical Details =<br />
<br />
* The notion of '''time stamp''' should be introduced in the data objects<br />
* Explicit differentiation between 4D and 3D+time<br />
<br />
== Time Stamp Proposal ==<br />
<br />
* [[ITK_Release_4/Video/Time Stamp|Time Stamp]]<br />
<br />
== Update ==<br />
<br />
* [[ITK_Release_4/Video/HowToBuildVideoModules|Build ITK Video modules with System installed OpenCV and VXL]]</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK/Release_4/Outreach/Tutorials/China_Visit_2011&diff=44117ITK/Release 4/Outreach/Tutorials/China Visit 20112011-12-07T15:12:38Z<p>Xiaoxiao: /* Schedules and Tutorial locations */</p>
<hr />
<div>= China Visit 2011 =<br />
==Purpose==<br />
<br />
==Tutorial==<br />
* Tutorial Title: '''ITKv4: Next Generation of Insight Segmentation and Registration Toolkit''' <br />
* Presenter: Xiaoxiao Liu from Kitware Inc.<br />
* Content<br />
** History of ITK<br />
** Open source facilities behind ITK( Git, CDash,Gerrit, Insight Journal)<br />
** What is new in ITKv4 ?<br />
*** Modularization<br />
*** Registration & Segmentation<br />
*** Bridge OpenCV<br />
*** How to migrate<br />
** Introduction to Simple ITK<br />
** How to contribute to ITKv4 (Adopt-A-Bug, Dashboard Fest)<br />
<br />
*Methodology<br />
The tutorial will include hands-on exercises performed on Virtual Machines that contain a pre-installed version of ITK and the related software tools.<br />
The tutorial will be delivered in Chinese (Mandarin), the materials will be in English.<br />
<br />
== Tutorial host institutions ==<br />
So far we've got three requests from the following institutions:<br />
*'''State Key Laboratory of Cognitive Neuroscience and Learning,National Key LaboratoryBeijing Normal University, Beijing'''<br />
* '''Shenzhen Key Lab of Neuro--Psychiatric Modulation, Shenzhen Institutes of Advanced Technology, CAS, Shenzhen'''<br />
*''' Institute for Pattern Recognition and Artificial Intelligence, Huazhong University of Science and Technology, Wuhan'''<br />
<br />
== Schedules and Tutorial locations ==<br />
* Tutorial at Wu Han <br />
**Dec. 19th (Monday), 2011, 2:30 PM<br />
**Hua Zhong U. of Science and Technology (Location TBA)<br />
<br />
* Tutorial at Shen Zhen<br />
**Dec. 28 (Wednesday), 2011, 2:30 PM<br />
**Room A601, West Wing, SIAT, 1068 Xueyuan Avenue, Shenzhen University Town, Shenzhen <br />
[Buses to SIAT:6,36,43,49,74,81,122,237;stop:SIAT]<br />
<br />
* Tutorial at Bei Jing<br />
**Jan. 6th (Friday), 2012, 2:30pm<br />
**The 3rd Floor Meeting Room of Brain Imaging Center, Beijing Normal University</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK/Release_4/Outreach/Tutorials/China_Visit_2011&diff=44116ITK/Release 4/Outreach/Tutorials/China Visit 20112011-12-07T15:12:11Z<p>Xiaoxiao: /* Schedules and Tutorial locations (TBA) */</p>
<hr />
<div>= China Visit 2011 =<br />
==Purpose==<br />
<br />
==Tutorial==<br />
* Tutorial Title: '''ITKv4: Next Generation of Insight Segmentation and Registration Toolkit''' <br />
* Presenter: Xiaoxiao Liu from Kitware Inc.<br />
* Content<br />
** History of ITK<br />
** Open source facilities behind ITK( Git, CDash,Gerrit, Insight Journal)<br />
** What is new in ITKv4 ?<br />
*** Modularization<br />
*** Registration & Segmentation<br />
*** Bridge OpenCV<br />
*** How to migrate<br />
** Introduction to Simple ITK<br />
** How to contribute to ITKv4 (Adopt-A-Bug, Dashboard Fest)<br />
<br />
*Methodology<br />
The tutorial will include hands-on exercises performed on Virtual Machines that contain a pre-installed version of ITK and the related software tools.<br />
The tutorial will be delivered in Chinese (Mandarin), the materials will be in English.<br />
<br />
== Tutorial host institutions ==<br />
So far we've got three requests from the following institutions:<br />
*'''State Key Laboratory of Cognitive Neuroscience and Learning,National Key LaboratoryBeijing Normal University, Beijing'''<br />
* '''Shenzhen Key Lab of Neuro--Psychiatric Modulation, Shenzhen Institutes of Advanced Technology, CAS, Shenzhen'''<br />
*''' Institute for Pattern Recognition and Artificial Intelligence, Huazhong University of Science and Technology, Wuhan'''<br />
<br />
== Schedules and Tutorial locations ==<br />
* Tutorial at Wu Han <br />
**Dec. 19th (Monday), 2011, 2:30 PM<br />
**Hua Zhong U. of Science and Technology (Location TBA)<br />
<br />
* Tutorial at Shen Zhen<br />
**Dec. 28, 2011, 2:30 PM<br />
**Room A601, West Wing, SIAT, 1068 Xueyuan Avenue, Shenzhen University Town, Shenzhen <br />
[Buses to SIAT:6,36,43,49,74,81,122,237;stop:SIAT]<br />
<br />
* Tutorial at Bei Jing<br />
**Jan. 6th (Friday), 2012, 2:30pm<br />
**The 3rd Floor Meeting Room of Brain Imaging Center, Beijing Normal University</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK/Release_4/Outreach/Tutorials/China_Visit_2011&diff=44115ITK/Release 4/Outreach/Tutorials/China Visit 20112011-12-07T15:06:27Z<p>Xiaoxiao: /* Schedules and Tutorial locations (TBA) */</p>
<hr />
<div>= China Visit 2011 =<br />
==Purpose==<br />
<br />
==Tutorial==<br />
* Tutorial Title: '''ITKv4: Next Generation of Insight Segmentation and Registration Toolkit''' <br />
* Presenter: Xiaoxiao Liu from Kitware Inc.<br />
* Content<br />
** History of ITK<br />
** Open source facilities behind ITK( Git, CDash,Gerrit, Insight Journal)<br />
** What is new in ITKv4 ?<br />
*** Modularization<br />
*** Registration & Segmentation<br />
*** Bridge OpenCV<br />
*** How to migrate<br />
** Introduction to Simple ITK<br />
** How to contribute to ITKv4 (Adopt-A-Bug, Dashboard Fest)<br />
<br />
*Methodology<br />
The tutorial will include hands-on exercises performed on Virtual Machines that contain a pre-installed version of ITK and the related software tools.<br />
The tutorial will be delivered in Chinese (Mandarin), the materials will be in English.<br />
<br />
== Tutorial host institutions ==<br />
So far we've got three requests from the following institutions:<br />
*'''State Key Laboratory of Cognitive Neuroscience and Learning,National Key LaboratoryBeijing Normal University, Beijing'''<br />
* '''Shenzhen Key Lab of Neuro--Psychiatric Modulation, Shenzhen Institutes of Advanced Technology, CAS, Shenzhen'''<br />
*''' Institute for Pattern Recognition and Artificial Intelligence, Huazhong University of Science and Technology, Wuhan'''<br />
<br />
== Schedules and Tutorial locations (TBA)==<br />
* Tutorial at Wu Han <br />
Dec. 19th (Monday), 2011, 2:30 PM<br />
Hua Zhong U. of Science and Technology <br />
<br />
* Tutorial at Shen Zhen<br />
Dec. 28, 2011, 2:30 PM<br />
Room A601, West Wing, SIAT.<br />
1068 Xueyuan Avenue, Shenzhen University Town, Shenzhen<br />
Buses to SIAT:<br />
6,36,43,49,74,81,122,237;stop:SIAT<br />
<br />
* Tutorial at Bei Jing<br />
Jan. 6th (Friday), 2012, 2:30pm<br />
The meeting room of Brain Imaging Center, 3rd floor. <br />
Beijing Normal University</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK/Release_4/Outreach/Tutorials/China_Visit_2011&diff=44094ITK/Release 4/Outreach/Tutorials/China Visit 20112011-12-06T04:40:09Z<p>Xiaoxiao: </p>
<hr />
<div>= China Visit 2011 =<br />
==Purpose==<br />
<br />
==Tutorial==<br />
* Tutorial Title: '''ITKv4: Next Generation of Insight Segmentation and Registration Toolkit''' <br />
* Presenter: Xiaoxiao Liu from Kitware Inc.<br />
* Content<br />
** History of ITK<br />
** Open source facilities behind ITK( Git, CDash,Gerrit, Insight Journal)<br />
** What is new in ITKv4 ?<br />
*** Modularization<br />
*** Registration & Segmentation<br />
*** Bridge OpenCV<br />
*** How to migrate<br />
** Introduction to Simple ITK<br />
** How to contribute to ITKv4 (Adopt-A-Bug, Dashboard Fest)<br />
<br />
*Methodology<br />
The tutorial will include hands-on exercises performed on Virtual Machines that contain a pre-installed version of ITK and the related software tools.<br />
The tutorial will be delivered in Chinese (Mandarin), the materials will be in English.<br />
<br />
== Tutorial host institutions ==<br />
So far we've got three requests from the following institutions:<br />
*'''State Key Laboratory of Cognitive Neuroscience and Learning,National Key LaboratoryBeijing Normal University, Beijing'''<br />
* '''Shenzhen Key Lab of Neuro--Psychiatric Modulation, Shenzhen Institutes of Advanced Technology, CAS, Shenzhen'''<br />
*''' Institute for Pattern Recognition and Artificial Intelligence, Huazhong University of Science and Technology, Wuhan'''<br />
<br />
== Schedules and Tutorial locations (TBA)==</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK/Release_4/Outreach/Tutorials/China_Visit_2011&diff=44091ITK/Release 4/Outreach/Tutorials/China Visit 20112011-12-05T19:55:08Z<p>Xiaoxiao: /* Tutorial */</p>
<hr />
<div>= China Visit 2011 =<br />
==Purpose==<br />
<br />
==Tutorial==<br />
* Tutorial Title: '''ITKv4: Next Generation of Insight Segmentation and Registration Toolkit''' <br />
* Presenter: Xiaoxiao Liu from Kitware Inc.<br />
* Content<br />
** History of ITK<br />
** Open source facilities behind ITK( Git, CDash,Gerrit, Insight Journal)<br />
** What is new in ITKv4 ?<br />
*** Modularization<br />
*** Registration & Segmentation<br />
*** Bridge OpenCV<br />
*** How to migrate<br />
** Introduction to Simple ITK<br />
** How to contribute to ITKv4 (Adopt-A-Bug, Dashboard Fest)<br />
<br />
*Methodology<br />
The tutorial will include hands-on exercises performed on Virtual Machines that contain a pre-installed version of ITK and the related software tools.<br />
The tutorial will be delivered in Chinese (Mandarin), the materials will be in English.<br />
<br />
== Tutorial host institutions ==<br />
So far we've got three requests from the following institutions:<br />
*''' Institute of Cognitive Neuroscience and Learning, National Key LaboratoryBeijing Normal University, Beijing'''<br />
* '''Shenzhen Key Lab of Neuro--Psychiatric Modulation, Shenzhen Institutes of Advanced Technology, CAS, Shenzhen'''<br />
*''' Institute for Pattern Recognition and Artificial Intelligence, Huazhong University of Science and Technology, Wuhan'''<br />
<br />
== Schedules and Tutorial locations (TBA)==</div>Xiaoxiaohttps://public.kitware.com/Wiki/index.php?title=ITK/Release_4/Outreach/Tutorials/China_Visit_2011&diff=44090ITK/Release 4/Outreach/Tutorials/China Visit 20112011-12-05T19:52:09Z<p>Xiaoxiao: /* Tutorial */</p>
<hr />
<div>= China Visit 2011 =<br />
==Purpose==<br />
<br />
==Tutorial==<br />
* Tutorial Title: '''ITKv4: Next Generation of Insight Segmentation and Registration Toolkit''' <br />
* Presenter: Xiaoxiao Liu from Kitware Inc.<br />
* Content<br />
** History of ITK<br />
** Open source facilities behind ITK( Git, CDash,Gerrit, Insight Journal)<br />
** What is new in ITKv4 ?<br />
*** Modularization<br />
*** Registration framework<br />
*** Bridge OpenCV<br />
*** Level Sets framework <br />
*** How to migrate<br />
*** Hands on exercises on migration<br />
** Introduction to Simple ITK<br />
** How to contribute to ITKv4 (Adopt-A-Bug, Dashboard Fest)<br />
<br />
*Methodology<br />
The tutorial will include hands-on exercises performed on Virtual Machines that contain a pre-installed version of ITK and the related software tools.<br />
The tutorial will be delivered in Chinese (Mandarin), the materials will be in English.<br />
<br />
== Tutorial host institutions ==<br />
So far we've got three requests from the following institutions:<br />
*''' Institute of Cognitive Neuroscience and Learning, National Key LaboratoryBeijing Normal University, Beijing'''<br />
* '''Shenzhen Key Lab of Neuro--Psychiatric Modulation, Shenzhen Institutes of Advanced Technology, CAS, Shenzhen'''<br />
*''' Institute for Pattern Recognition and Artificial Intelligence, Huazhong University of Science and Technology, Wuhan'''<br />
<br />
== Schedules and Tutorial locations (TBA)==</div>Xiaoxiao