Difference between revisions of "Engineering:Subversion Repository"

From NAMIC Wiki
Jump to: navigation, search
m (Text replacement - "http://www.slicer.org/slicerWiki/index.php/" to "https://www.slicer.org/wiki/")
 
(29 intermediate revisions by 8 users not shown)
Line 1: Line 1:
== What is NA-MIC Subversion ==
+
== What is the NA-MIC Sandbox ==
  
 
NA-MIC SandBox is a repository of untested and unstable code developed as a part of NA-MIC. For more information, check the [[NAMIC_Wiki:Software_Process#The_Sandbox|NA-MIC Software Development Process]]
 
NA-MIC SandBox is a repository of untested and unstable code developed as a part of NA-MIC. For more information, check the [[NAMIC_Wiki:Software_Process#The_Sandbox|NA-MIC Software Development Process]]
  
See [http://svnbook.red-bean.com/ the SVN Book at red-bean.com]. In particular, check out the information about [http://svnbook.red-bean.com/en/1.1/ch03s05.html the Basic Work Cycle for svn].
+
This source code repository is managed using "[http://en.wikipedia.org/wiki/Subversion_(software) Subversion]".  
  
The NA-MIC SVN is also used for the [[Slicer3|Slicer3]] development effort.
+
For information on how to use Subversion, please see [http://svnbook.red-bean.com/ the SVN Book at red-bean.com]. In particular, check out the information about [http://svnbook.red-bean.com/en/1.1/ch03s05.html the Basic Work Cycle for svn].
 +
 
 +
The NA-MIC SVN is also used for the [https://www.slicer.org/wiki/Main_Page Slicer3] development effort.
  
 
== How do I get NA-MIC SandBox ==
 
== How do I get NA-MIC SandBox ==
  
Use [http://subversion.tigris.org/ Subversion]. Checkout using the following command:
+
First, you should install a  [http://subversion.tigris.org/ Subversion] client in your computer. They are available for most operating systems. Please check if you already have Subversion on the system, or download appropriate one from http://subversion.tigris.org/project_packages.html. On Linux and Cygwin platforms you simply need to check if the "svn" command is available.
  
svn checkout http://www.na-mic.org/svn/NAMICSandBox
+
Once you have a subversion client, you can checkout the NA-MIC Sandbox by using the following command:
  
Clients for subversion are avaialble for most operating systems. Please check if you already have Subversion on the system, or download apropriate one from http://subversion.tigris.org/project_packages.html.
+
svn checkout http://svn.na-mic.org/NAMICSandBox/trunk NAMICSandBox
  
 
== How do I commit to NA-MIC Subversion ==
 
== How do I commit to NA-MIC Subversion ==
Line 55: Line 57:
 
== Can I see the files through the Web ==
 
== Can I see the files through the Web ==
  
Yes, check: [http://www.na-mic.org/websvn/listing.php?repname=NAMICSandBox&path=%2F&sc=0 WebSVN].
+
Yes, check: [http://viewvc.slicer.org/viewcvs.cgi/?root=NAMICSandBox ViewVC].
  
Or for Slicer3, [http://www.na-mic.org/websvn/listing.php?repname=Slicer3&path=%2F&sc=0 WebSVN].
+
Or for Slicer3, [http://viewvc.slicer.org/viewcvs.cgi/?root=Slicer3 ViewVC].
  
 
== How do I make a release branch? ==
 
== How do I make a release branch? ==
Line 63: Line 65:
 
Use the copy command like:
 
Use the copy command like:
  
  svn copy http://www.na-mic.org/svn/Slicer3/trunk http://www.na-mic.org/svn/Slicer3/branches/Slicer3.0-PostAHMBeta -m "ENH: new branch to capture work done at the 2007 all hands meeting"
+
  svn copy http://svn.slicer.org/Slicer3/trunk/ http://svn.slicer.org/Slicer3/branches/Slicer3.0-PostAHMBeta -m "ENH: new branch to capture work done at the 2007 all hands meeting"
  
 
== How can I switch between branches and the trunk? ==
 
== How can I switch between branches and the trunk? ==
Line 69: Line 71:
 
You can switch your current checkout to the branch with:
 
You can switch your current checkout to the branch with:
  
  svn switch http://www.na-mic.org/svn/Slicer3/branches/Slicer3.0-PreAHMBeta
+
  svn switch http://svn.slicer.org/Slicer3/branches/Slicer3.0-PreAHMBeta
  
 
and get back to the head with:
 
and get back to the head with:
  
  svn switch http://www.na-mic.org/svn/Slicer3/trunk  
+
  svn switch http://svn.slicer.org/Slicer3/trunk  
  
 
Once you have switched, you can do updates and commits to that branch.
 
Once you have switched, you can do updates and commits to that branch.
Line 79: Line 81:
 
== Merging latest changes from the HEAD into your branch ==
 
== Merging latest changes from the HEAD into your branch ==
  
  svn merge http://www.na-mic.org/svn/Slicer3/trunk http://www.na-mic.org/svn/Slicer3/branches/testing/sign_integration/Slicer3
+
  svn merge http://svn.slicer.org/Slicer3/trunk http://svn.slicer.org/Slicer3/branches/testing/sign_integration/Slicer3
  
 
Note: this will not get new files, just changes to existing files.
 
Note: this will not get new files, just changes to existing files.
Line 92: Line 94:
 
== How can I merge changes from once branch into another? ==
 
== How can I merge changes from once branch into another? ==
  
See [http://svnbook.red-bean.com/en/1.2/svn.branchmerge.commonuses.html this part of the svn documentation].
+
To move changes from the current trunk head ''into'' a branch see [http://svnbook.red-bean.com/en/1.2/svn.branchmerge.commonuses.html this part of the svn documentation] or follow the instructions below:
 +
 
 +
* Find out the initial version number of the branch by executing: 
 +
 
 +
svn log --verbose --stop-on-copy http://svn.slicer.org/Slicer3/branches/Slicer3.0-PreAHMBeta
 +
 
 +
from which you'll see a revision number for the commit that created the branch. The number is specified by the oldest (last) log entry and starts with an r. In this case it is r2137.
 +
 
 +
* Find out the current revision number of the trunc by executing
 +
 
 +
svn update
 +
 
 +
In my example it is 2157. 
 +
 
 +
* Bring changes up through 2157 into the branch, you run the following command from within the directory that has the branch:
 +
 
 +
svn merge -r2137:2157 http://svn.slicer.org/Slicer3/trunk
 +
 
 +
If you do 'svn status' the new files will show up as modified and/or conflicts. 
 +
 
 +
* Resolve any conflicts:
 +
 
 +
  svn status | grep "C "
  
 +
[[Engineering:Subversion_Repository#Conflicts_in_the_file| See ]]  on how to resolve conflicts
  
For example: to move changes from the current trunk head ''into'' a branch, you need to first know the version of the branch, which you can get as follows:
+
* Update and compile libraries in Slicer3-lib by executing 
  
svn log --verbose --stop-on-copy http://www.na-mic.org/svn/Slicer3/branches/Slicer3.0-PreAHMBeta
+
  Slicer3/Scripts/genlib.tcl
  
from which you'll see a revision number for the commit that created the branch (in this case r2137).
+
* Compile Slicer3 by executing make in Slicer3-build
  
Then in the trunk, do an svn update to get the current revision number.  In my example it is 2157.  To bring changes up through 2157 into the branch, you run the following command from within the directory that has the branch:
+
* Commit all new files (also the once that were added/updated from the trunc) to the branch by executing in the source directory :
 +
 +
svn commit -m "ENH:  Update my branch with current trunc - r2137:2157"
  
svn merge -r2137:2157 http://www.na-mic.org/svn/Slicer3/trunk
+
Note, add r2137:2157 in the log file so next time you update the branch by executing
  
If you do 'svn status' the new files will show up as modified and/or conflicts. You need to commit them to actually put them into the branch.
+
svn merge -r2158:XXXX http://svn.slicer.org/Slicer3/trunk
  
 
== I get the following error when I try to commit... ==
 
== I get the following error when I try to commit... ==
Line 158: Line 185:
  
 
   sed -i -e 's/\t/  /g' <FileName>
 
   sed -i -e 's/\t/  /g' <FileName>
 +
 +
=== Windows new-lines in the source file ===
 +
 +
<nowiki>----------------------------------------------------------------------
 +
Problems in file "trunk/AnalyzeObjectReader/objectutils.h":
 +
The following line(s) contain windows new-lines:
 +
    1: /*************************************************************************
 +
    2: Copyright (c) 2007, Regents of the University of Iowa
 +
    3:
 +
    4: All rights reserved.
 +
    5:
 +
 +
Found problems with 1 file(s). Cannot commit
 +
----------------------------------------------------------------------</nowiki>
 +
 +
Make sure there are no windows new-lines in the source files. You can remove them with
 +
 +
  sed -i -e 's/^M//g' <FileName>
 +
 +
where the "^M" is typed by pressing the control key with the v-key followed by control key with the m-key.
  
 
=== Missing new line at the end of file ===
 
=== Missing new line at the end of file ===
Line 212: Line 259:
  
 
...snip...
 
...snip...
 +
 +
== Usage Example ==
 +
 +
=== Description ===
 +
 +
Below is a (hypothetical) example of the typical use of the NA-MIC Sandbox.
 +
 +
* A group collaborating in NA-MIC is developing software for segmenting tumors.
 +
* The group wants to share this code with other groups and eventually contribute it to one of the toolkits in the NA-MIC Kit, or to Slicer
 +
* First the code must be brought to work on representative use cases
 +
* Then the code is to be tried out by members of other groups.
 +
* In order to share and test the code, the first group contributes it in a sub-directory of the NA-MIC Sandbox
 +
* The content of the sub-directory must include '''ALL''' the material that other group may need in order to get this code to work. (with the exception of large datasets, for which a link to a public database will be preferred).
 +
* One of the sub-directories of the new directory will include a technical report describing the code and how to use it.
 +
** This report will be submitted later as a paper to the [Insight journal].
 +
* Other groups will get the material by updating their local checkouts of the NA-MIC Sandbox
 +
** They will try the code
 +
** They will send comments back to the original group
 +
** They will modify and improve the code, and commit their changes back to the repository
 +
 +
=== How to do it ===
 +
 +
The steps that must be followed by the first group are
 +
 +
# Checkout the NA-MIC Sandbox into a local computer
 +
# As a sub-directory of the "trunk" directory, create a new directory with a name descriptive of the project (e.g. TumorSegmentationMethodX in this case).
 +
# Add the directory by using the command '''svn add TumorSegmentationMethodX'''.
 +
# Cd in the directory and create the following typical tree
 +
## Source
 +
## Testing
 +
## Documents
 +
### Report01
 +
# Add each one of the subdirectories by using the command '''svn add directoryname'''
 +
# At the top of the TumorSegmentationMethodX directory, create the files
 +
## CMakeLists.txt
 +
## CTestConfig.cmake
 +
# Add them to the repository by using the commands
 +
## svn add CMakeLists.txt
 +
## svn add CTestConfig.cmake
 +
## svn commit -m "ENH: Configuration files"
 +
# In the "Source" sub-directory add the source code files implementing their algorithm.
 +
# In the "Testing" sub-directory add the source code files testing '''ALL''' the features of their algorithm.
 +
## For this, a CMakeLists.txt file must be added in the Testing sub-directory and it should include ADD_TEST commands in generous profusion.
 +
# Once all the code '''and Tests''' are added to the sub-directory, a build of the code will be made in a separate binary tree. From that binary tree, builds will be submitted to one of the NA-MIC kit Dashboard (e.g. ITK, VTK, Slicer). The Dashboard to use will depend on the nature of the source code. In this case, since this is a segmentation method, the ITK Dashboard will be the proper location. The submission should be posted as Experimental builds to avoid confusion with the standard builds of that Dashboard.
 +
 +
 +
Steps to be followed by other groups are
 +
 +
# Update their local checkouts of the NA-MIC Sandbox
 +
## This can be done with the command '''svn update'''
 +
## This should bring the new directory TumorSegmentationMethodX
 +
# Make a build of the code in a separate binary tree
 +
# Submit a build to the Dashboard
 +
# Test the code with their own images
 +
# Make improvements to the code and commit them to the repository with the command '''svn commit -m "ENH: This changes improves..." '''
 +
## The content of the "-m" message is extremely important. You must write it from the perspesctive of considering a developer unfamiliar with the code, reading this comments five years later. Please write clear and generous messages. Lazy developers who write short commit messages will automatically accumulate bad Karma and will be condemned to reincarnate as users of buggy operating systems with lousy customer support.

Latest revision as of 17:09, 10 July 2017

Home < Engineering:Subversion Repository

What is the NA-MIC Sandbox

NA-MIC SandBox is a repository of untested and unstable code developed as a part of NA-MIC. For more information, check the NA-MIC Software Development Process

This source code repository is managed using "Subversion".

For information on how to use Subversion, please see the SVN Book at red-bean.com. In particular, check out the information about the Basic Work Cycle for svn.

The NA-MIC SVN is also used for the Slicer3 development effort.

How do I get NA-MIC SandBox

First, you should install a Subversion client in your computer. They are available for most operating systems. Please check if you already have Subversion on the system, or download appropriate one from http://subversion.tigris.org/project_packages.html. On Linux and Cygwin platforms you simply need to check if the "svn" command is available.

Once you have a subversion client, you can checkout the NA-MIC Sandbox by using the following command:

svn checkout http://svn.na-mic.org/NAMICSandBox/trunk NAMICSandBox

How do I commit to NA-MIC Subversion

Fill the form at https://www.kitware.com/Admin/SendPassword.cgi and under Comment type "Request password for NA-MIC Sandbox". Once you have access to write to NA-MIC SandBox, you can work with repository using the following commands:

To update repository:

svn update

To check current state of your edits:

svn status

To check the current state compared to the repository:

svn -u status

To add new file:

svn add filename

followed by (very important):

svn commit -m"ENH: Adding a new file" filename

To remove file:

svn remove filename

To rename file:

svn move oldname newname

If the update results in conflict, fix the file first before commiting it.

Once you have fixed the file:

svn resolved <filename>

Can I see the files through the Web

Yes, check: ViewVC.

Or for Slicer3, ViewVC.

How do I make a release branch?

Use the copy command like:

svn copy http://svn.slicer.org/Slicer3/trunk/ http://svn.slicer.org/Slicer3/branches/Slicer3.0-PostAHMBeta -m "ENH: new branch to capture work done at the 2007 all hands meeting"

How can I switch between branches and the trunk?

You can switch your current checkout to the branch with:

svn switch http://svn.slicer.org/Slicer3/branches/Slicer3.0-PreAHMBeta

and get back to the head with:

svn switch http://svn.slicer.org/Slicer3/trunk 

Once you have switched, you can do updates and commits to that branch.

Merging latest changes from the HEAD into your branch

svn merge http://svn.slicer.org/Slicer3/trunk http://svn.slicer.org/Slicer3/branches/testing/sign_integration/Slicer3

Note: this will not get new files, just changes to existing files.

How can I tell if I'm on the branch or the trunk?

Look at the URL line from

svn info


How can I merge changes from once branch into another?

To move changes from the current trunk head into a branch see this part of the svn documentation or follow the instructions below:

  • Find out the initial version number of the branch by executing:
svn log --verbose --stop-on-copy http://svn.slicer.org/Slicer3/branches/Slicer3.0-PreAHMBeta

from which you'll see a revision number for the commit that created the branch. The number is specified by the oldest (last) log entry and starts with an r. In this case it is r2137.

  • Find out the current revision number of the trunc by executing
svn update 

In my example it is 2157.

  • Bring changes up through 2157 into the branch, you run the following command from within the directory that has the branch:
svn merge -r2137:2157 http://svn.slicer.org/Slicer3/trunk

If you do 'svn status' the new files will show up as modified and/or conflicts.

  • Resolve any conflicts:
 svn status | grep "C "

See on how to resolve conflicts

  • Update and compile libraries in Slicer3-lib by executing
 Slicer3/Scripts/genlib.tcl
  • Compile Slicer3 by executing make in Slicer3-build
  • Commit all new files (also the once that were added/updated from the trunc) to the branch by executing in the source directory :
svn commit -m "ENH:  Update my branch with current trunc - r2137:2157" 

Note, add r2137:2157 in the log file so next time you update the branch by executing

svn merge -r2158:XXXX http://svn.slicer.org/Slicer3/trunk

I get the following error when I try to commit...

If you want to enable this error reporting on your subversion repository, please follow instructions about Subversion Input Filters.

Commit log error

The error would look like this:

---------------------------------------------------------------------
 Subversion Commits to NA-MIC require commit type in the comment.
 Valid commit types are:
   BUG:   - a change made to fix a runtime issue
            (crash, segmentation fault, exception, or incorrect result,
   COMP:  - a fix for a compilation issue, error or warning,
   ENH:   - new functionality added to the project,
   PERF:  - a performance improvement,
   STYLE: - a change that does not impact the logic or execution of the code.
            (improve coding style, comments, documentation).
 
 The Subversion command to commit the change is:
 
   svn commit -m "BUG: fixed core dump when passed float data" filename
 
 you can also use the syntax below which omits the -m flag. In this case
 subversion will start up an editor for you to enter a comment on why you made
 the change.
 
   svn commit filename
 ----------------------------------------------------------------------

Make sure to start the commit message with one of the specified tags.


Tabs in the source file

----------------------------------------------------------------------
 Problems in file "my baby.cxx":
 The following line(s) contain tabs:
     4: This line contains a tab-->      <--
 
 Found problems with 1 file(s). Cannot commit
 ----------------------------------------------------------------------

Make sure there is no tabs in the source files. You can remove them with

perl -pi .-e 's/\t/    /g' <FileName>

or

 sed -i -e 's/\t/  /g' <FileName>

Windows new-lines in the source file

----------------------------------------------------------------------
Problems in file "trunk/AnalyzeObjectReader/objectutils.h":
The following line(s) contain windows new-lines:
    1: /*************************************************************************
    2: Copyright (c) 2007, Regents of the University of Iowa
    3: 
    4: All rights reserved.
    5: 

Found problems with 1 file(s). Cannot commit
 ----------------------------------------------------------------------

Make sure there are no windows new-lines in the source files. You can remove them with

 sed -i -e 's/^M//g' <FileName>

where the "^M" is typed by pressing the control key with the v-key followed by control key with the m-key.

Missing new line at the end of file

----------------------------------------------------------------------
 Problems in file "my baby.cxx":
 The following line(s) do not contain new-line character:
     5: another linex
 
 Found problems with 1 file(s). Cannot commit
 ----------------------------------------------------------------------

Make sure there is a new line at the end of the source file. Most editors should fix this automatically.

Conflicts in the file

----------------------------------------------------------------------
 Problems in file "test.cxx":
 The following line(s) contain conflicts:
     1: <<<<<<< .mine
    11: =======
    22: >>>>>>> .r13
 
 Found problems with 2 file(s). Cannot commit
 ----------------------------------------------------------------------

Make sure to remove any conflicts before removing files.

Once resolved:

svn resolved test.cxx

Things missing from SVN that were in CVS

No cvs diff -w

Some workarounds here: http://kitt.hodsden.com/ignoring_whitespace_changes_with_svn_diff

No cvs update -C

Remove the file and then update (nothing more clean?) (mathieu). I believe this is describe here: http://svnbook.red-bean.com/nightly/en/svn.tour.cycle.html#svn.tour.cycle.resolve

...snip...

If you get a conflict, you need to do one of three things:

  • Merge the conflicted text “by hand” (by examining and editing the conflict markers within the file).
  • Copy one of the temporary files on top of your working file.
  • Run svn revert <filename> to throw away all of your local changes.

Once you've resolved the conflict, you need to let Subversion know by running svn resolved. This removes the three temporary files and Subversion no longer considers the file to be in a state of conflict.

$ svn resolved <filename>

...snip...

Usage Example

Description

Below is a (hypothetical) example of the typical use of the NA-MIC Sandbox.

  • A group collaborating in NA-MIC is developing software for segmenting tumors.
  • The group wants to share this code with other groups and eventually contribute it to one of the toolkits in the NA-MIC Kit, or to Slicer
  • First the code must be brought to work on representative use cases
  • Then the code is to be tried out by members of other groups.
  • In order to share and test the code, the first group contributes it in a sub-directory of the NA-MIC Sandbox
  • The content of the sub-directory must include ALL the material that other group may need in order to get this code to work. (with the exception of large datasets, for which a link to a public database will be preferred).
  • One of the sub-directories of the new directory will include a technical report describing the code and how to use it.
    • This report will be submitted later as a paper to the [Insight journal].
  • Other groups will get the material by updating their local checkouts of the NA-MIC Sandbox
    • They will try the code
    • They will send comments back to the original group
    • They will modify and improve the code, and commit their changes back to the repository

How to do it

The steps that must be followed by the first group are

  1. Checkout the NA-MIC Sandbox into a local computer
  2. As a sub-directory of the "trunk" directory, create a new directory with a name descriptive of the project (e.g. TumorSegmentationMethodX in this case).
  3. Add the directory by using the command svn add TumorSegmentationMethodX.
  4. Cd in the directory and create the following typical tree
    1. Source
    2. Testing
    3. Documents
      1. Report01
  5. Add each one of the subdirectories by using the command svn add directoryname
  6. At the top of the TumorSegmentationMethodX directory, create the files
    1. CMakeLists.txt
    2. CTestConfig.cmake
  7. Add them to the repository by using the commands
    1. svn add CMakeLists.txt
    2. svn add CTestConfig.cmake
    3. svn commit -m "ENH: Configuration files"
  8. In the "Source" sub-directory add the source code files implementing their algorithm.
  9. In the "Testing" sub-directory add the source code files testing ALL the features of their algorithm.
    1. For this, a CMakeLists.txt file must be added in the Testing sub-directory and it should include ADD_TEST commands in generous profusion.
  10. Once all the code and Tests are added to the sub-directory, a build of the code will be made in a separate binary tree. From that binary tree, builds will be submitted to one of the NA-MIC kit Dashboard (e.g. ITK, VTK, Slicer). The Dashboard to use will depend on the nature of the source code. In this case, since this is a segmentation method, the ITK Dashboard will be the proper location. The submission should be posted as Experimental builds to avoid confusion with the standard builds of that Dashboard.


Steps to be followed by other groups are

  1. Update their local checkouts of the NA-MIC Sandbox
    1. This can be done with the command svn update
    2. This should bring the new directory TumorSegmentationMethodX
  2. Make a build of the code in a separate binary tree
  3. Submit a build to the Dashboard
  4. Test the code with their own images
  5. Make improvements to the code and commit them to the repository with the command svn commit -m "ENH: This changes improves..."
    1. The content of the "-m" message is extremely important. You must write it from the perspesctive of considering a developer unfamiliar with the code, reading this comments five years later. Please write clear and generous messages. Lazy developers who write short commit messages will automatically accumulate bad Karma and will be condemned to reincarnate as users of buggy operating systems with lousy customer support.