Maintenance/Contribute

Overview

HOW-TO for modifying and contributing to the davinci library/examples c.edwards 12/21/2007

The library and examples are version controlled by a program called SubVersion (SVN). This allows for easy roll-backs to previous versions in case something bad happens. Unfortunately as a result of this added functionality it requires a little understanding of how SVN works, and what steps need to be taken to ensure proper development and documentation.

Common SVN Commands

Shortcuts are given in parentheses, use "svn help" for more details

Local Copy Modification Actions

These actions cause changes to your local/working copy of the repository. Only your work can changed using these commands. The SVN repository will remain untouched.

svn checkout (co)    - used to checkout a copy from the SVN repository
svn status (st)      - compares the status of your local copy to the SVN repository
svn update (up)      - updates your local copy to the current version (overwrites your local changes)

Repository modification actions

These actions cause changes to the SVN repository. Your work will not be changed but changes will be made to the SVN repository.

svn commit (ci) 'filename'      - commit your changes to the repository
svn add 'filename'              - add a file to the repository (requires a commit afterwords)
svn delete (rm) 'filename'      - delete a file from the repository (requires a commit afterwords)

The Cookbook

This is the standard method for checking out, modifying and committing changes

Step 1

Checkout a copy of the library/examples and put it in a local place

mkdir /u/cedwards/davinci_lib/
cd /u/cedwards/davinci_lib/
svn co file:///tes/svn/dev/davinci_library/trunk/ library
svn co file:///tes/svn/dev/davinci_examples/trunk/ examples

This creates 2 local SVN directories called library and examples in /u/cedwards/davinci_library

As SVN works to copy the files you will see the something like:

A      "somefile.dvrc" 

Indicating that SVN has added a file called "somefile.dvrc"

Step 2

Change to the library directory and modify some code!

Please follow syntax and spacing in place by in the library and try for neat, clean, and efficient code (in this example misc.dvrc and utils.dvrc will be changed)

Step 3

Try checking the status of the local copy

svn st
M      misc.dvrc
M      utils.dvrc

Indicating that two files have been modified.

Other common descriptions include (use "svn help st" for more info):

A (added), D (deleted), M (modified)
C (conflict), ! (not found), ? (not in SVN)

Step 4

Once you are satisfied by the changes you have made commit them to SVN

svn ci misc.dvrc utils.dvrc

A window with your default editor (set by the $EDITOR enviornment variable) will open.  Enter in as much detail possible the changes made to the files making sure to stay above the "ignore line"

In this case, the wiki() function was moved from misc.dvrc to utils.dvrc as it seems like a more appropriate location for the wiki() function.

Save and quit the editor which will transmit the data to the repository

Sending        misc.dvrc
Sending        utils.dvrc
Transmitting file data ..
Committed revision 8231.

Step 5

Now the repository has your changes. Lets say you come back to work on something else a few weeks later. You will always want to update your copy

svn update
At revision 8231.

If you see this you are good to go, but if you see something else, that indicates that your copy was out of date and is now upto date.

NOTE: It is very important to make sure you are editing the most upto date copy as conflicts can arise if you aren't!

Step 6

Now make sure to edit a wiki page with the function name using the exact same format as the rest of the wiki, which is accomplished largely by using templates.

a. Make a URL with the following format http://davinci.asu.edu/index.php/my_new_function
b. Replace "my_new_function" with the EXACT name of your function
c. Begin editing the page following the "DavinciWiki Function" template.

See: http://davinci.asu.edu/index.php/Wiki_Maintenance#How-To_Make_a_New_Function_Page

Additional Information

A list of the dvrc and example files along with a short description is listed on:

To add a file to a repository you must use 2 commands. The most common reason to add files is to the examples directory. Many functions require external files to function properly.

Adding a file to the examples folder

cd /u/cedwards/davinci_lib/examples        - change to the local examples SVN repository
cp /u/cedwards/myfile.txt myfile.txt       - copy desired file to local SVN repository
svn add myfile.txt                         - this adds the file to the SVN repository
svn ci myfile.txt                          - this commits the changes and copies the file to the SVN repository

Maintenance/Contribute

Contents