wiki:devUsingSVN

Using Subversion

Setting up a repo
Editing commands

Update your local repository
File Management Commands
Checking your work
Committing your work

Best Practices

Setup your workspaces
Edit in the right sequence
Make small changes, make them one at a time
Make backups of the current files on protostar
Keep the servers clean
Communicate with your fellow developers
Think before you touch

References


Setting up a repo

Please read the section on best practices before moving things to the servers (even the test environment)!

A 'repo' is a repository where code is kept. All code in a given project is kept in a central repo (usually referred to as the 'remote repo') and you basically download a local repo where you do your own work. When you're done, you send your changes up to the big repo in the sky and it gets merged into the rest of the source code. If someone has modified the same file as you have, Subversion (the software that manages the repos) helps negotiate the process of merging your changes with theirs. Project conifer has two basic repos:

http://svn.open-ils.org/trac/ILS/ - this is the repo for core Evergreen code, aka the stuff developed by Equinox developers

http://svn.open-ils.org/trac/ILS-Contrib/ - this is the repo for contributed evergreen code aka the stuff contributed by the community

Basically, you will probably never need to ever work with the ILS repo, therefore everything that follows concerns ILS-Contrib

To set up a repo, use the following command:

   sudo svn co --username <your username> --password <your password> svn://svn.open-ils.org/ILS-Contrib/conifer/trunk <name of local directory>

So, if your username was 'tom' and your password 'jones', and you wanted to bring down contrib and drop it in a folder called My-ILS-Contrib

   sudo svn co --username tom --password jones svn://svn.open-ils.org/ILS-Contrib/conifer/trunk My-ILS-Contrib

Note svn will create the My-ILS-Contrib directory if it doesn't exist.

If you get an error saying bash has no idea what an svn is, you need to install it.

   sudo apt-get install svn

That ought to do it. Then run the command above.


Editing commands

It's important to remember that the files in the repo are under version control. Copying (cp) or moving (mv) commands will allow you to move a new file into your local repo directory, but it doesn't tell svn that you want the file under version control. If you mv a file into My-ILS-Contrib, when you checkin your files, it won't be sent up to the server when you next check them in.

If you want to edit the files in the local repo you need to use the svn versions of the normal Linux command. The name of each command pretty much tells you all you need to know. They use the same syntax as their Linux counterparts, and behave the same way, the difference is that they also inform svn of your changes. You should use the svn versions of these kinds of commands (explained below) to prevent your local repo from corrupting.


Update your local repository

Use the update command to update your local repository - not the remote one . Update will pull any new files down that have been changed or added since you created your local repo. You run it by moving into your local repo and then typing

svn update

You will see output like:

U    circ/circ_duration.js
A    circ/circ_lib.js
U    circ/circ_duration_OWAL.js
U    circ/circ_permit_copy.js
U    circ/circ_duration_OWA.js

This means that since I checked out my local repo someone has added a new page: circ_lib.js (note the 'A'), and someone (maybe different people) have made changes (updated) 3 other files.

You should always run this command before you sit down to do some work, especially if you haven't touched your repo in a long time. By updating, you ensure you're looking at the most recent version of the files.


File Management Commands

These are your basic commands for editing and the ones you'll be using the most. For more information, see the excellent explanation at:

http://svnbook.red-bean.com/en/1.5/svn.tour.cycle.html#svn.tour.cycle.edit

svn add    # adds a new file to the repo

svn delete # removes a file from the repo

svn move   # moves a file to a different part of the repo

svn copy   # copies a file from one part of the repo to another part of the repo

svn mkdir  # makes a new directory in the repo

Checking your work

After you make your changes, you should check to see what changes you made before you send up your stuff. Lets say you inadvertently changed someone elses file (you opened it to take a look at an example and you changed theirs by mistake). It's good to know about this before committing it to the repo so you can revert the changes. You run this command with:

svn status

You'll see a list of files that changed. You can get more information with the -u option.

svn status -u

This will also show you the files that you've changed, but it will also show you which ones are different in the remote repo from your local copy; they're shown with an * beside them. This means you should do an update before you commit.

For a more detailed list of the actual changes you can use:

svn diff

which lists the content of the files you changed with a + beside lines you added or - for lines you removed.

This allows you to undo a change. If you don't want a change in a file committed by ci you can simply

svn revert <filename>

Note it's important to remember that revert removes every change you made in the file. Keep that in mind.


Committing your work

checkin or simply ci allows you to commit your changes to the remote repository.

 svn ci --username <username> --password <password> -m "added reserves link to algoma footer"

Always try to use the -m options. This is a simple string that gives a description of the change you made. It really helps keep track of things because the tags themselves are only numbers.


Best Practices

Setup your workspaces

Set up your workspaces with the co (checkout) command. It should only need to be done once. From this point forward you use svn update to keep them up to date. Putting a local repo in your home directory on the servers is fine. Contrib is only about 6.3MB

1) Set up a local repo on a development computer at home or in your office (probably a linux laptop)

2) Set up a local repo in your home directory on comet.

3) Set up a local repo in your home directory on protostar.


Edit in the right sequence

Work goes from your laptop > comet > protostar. Use svn to move the files in each case from one local repo to the next (see 'Setup your workspaces' above). Always follow the sequence below! Every time you make a change.

So the sequence is:

Workspace Step Command
laptop update svn update
edit svn add, copy etc
check work svn status etc
commit changes svn ci
comet update svn update
edit svn add, copy etc
check work svn status etc
commit changes svn ci
protostar update svn update
move files into place standard shell commands

Make small changes, make them one at a time

If you make 25 changes at one go and then make a commit, that one commit will move all 25 changes up to Trac. This is bad because:

1) If there's a problem with 1 of your 25 changes and we need to move to an earlier version, you loose the other 24 changes.

2) You only get to add one description to each commit (-m option). It gets pretty meaningless if it's a page long.

3) You should test each change thoroughly before you make another. That way you always know what caused a problem. If you make 25 changes at a time and something goes wrong, it's very difficult to figure out which of the 25 changes caused the problem.


Make backups of the current files on protostar

Sure, svn allows us to rollback to an earlier version of code in the event that something goes wrong. But if you follow the point above, and make small changes at a time, then backing up and restoring the original file is a pretty fast and easy way to rollback a change. Restoring the original file gives you time to go back to your laptop and comet to figure out what happened and to make a solid fix.


Keep the servers clean

When you work with files on the server and you make backups etc, try to remember to go back and clean them up. Try to stick to the following rules:

1) When you backup a file, move the original into your home dir, don't leave them cluttering up the working directories.

2) Check that your preferred editor is not cluttering up the working directories with temp files (ie circ_groups.js~7~)You can change this default behaviour by changing the settings on your editor, just ask google how.


Communicate with your fellow developers

Or rather, be reachable while you're developing. In other words, if you're logged into the server, you should be also logged into esi-conifer or on IM so that if someone is about to restart postgres on darkmatter they can give you a heads up. If you aren't reachable then any problems resulting from the actions of others is your problems, sorry.


Think before you touch

A lot of the files are shared by everyone. Keep that in mind. Feel free to mess about with circ_permit_MYOU.js all you want, it only effects your library. circ_groups.js effects everyone -- think before you mess around with the file or any of the values on it. If you have any doubts about a file, ask.

Also keep in mind the hours of various libraries. If you are going to need a restart, try to hold off to the evening.


References

http://svnbook.red-bean.com/en/1.5/index.html

http://svnbook.red-bean.com/nightly/en/svn.intro.quickstart.html

Last modified 13 years ago Last modified on Sep 25, 2009, 1:26:26 PM