How to use subversion for OpenLaszlo collaborative development author: benjamin shine ben@laszlosystems.com last modified: 2007-08-31 by ptw copyright: 2006-2007 SYNOPSIS: source svn-bash.sh SEE ALSO: openlaszlo/tools/trunk/env/setup-lps.sh EXECUTIVE SUMMARY: 1. To use the tools you need to: % source $MYSVNHOME/tools/trunk/svn/svn-bash.sh (if you have not already). If you will use the tools often, consider adding the `source` directive to your .bashrc 2. If you have a preferred editor, you should set your $EDITOR environment variable to that. If you do not want to be prompted for your password when checking in, you should set $SVNPASSWORD to your password. 3. To make a change for review, you need to be in your svn workspace. If you want, you can be in a sub-directory, in which case only files changed in that sub-directory will be considered. By convention, it is best if you are a the root of your workspace ($LPS_HOME) -- otherwise your reviewer must examine the change to figure out where to apply it. 4. Invoke % svn-editchange This will start a new change description (or resume an existing one, if you already have one started), and invoke $EDITOR to edit it. You should fill in the change template details. You should nominate reviewers in the change template. Please elide any sections that are not applicable. [NOTE: The list of files in the change text is taken from what svn believes is modified at the time you first invoke `svn-editchange`. This list of files will be used to drive the remainder of the change process. If you add, modify, or revert files after starting your change, you MUST update the file list by invoking: % svn-updatechange which will update the file list and then invoke your editor on the updated change description.] 5. When you are happy with your change text, invoke % svn-review This will check your change in to svn so that your reviewer can retrieve it and review it. On OS X and Cygwin, it will compose a mail message addressed to your reviewers. On other platforms it will output the message to standard out; you can pipe it to your favorite mailer, or copy and paste. 6. The reviewer can approve or reject your change. In either case they may offer comments. For an approved change, addressing the comments is recommended but not required. For a rejected change, you must address the comments and re-submit for review. 7. You can update your change text by invoking % svn-updatechange If you have not modified, added or removed any files in addressing the review comments, it will be faster to use % svn-editchange which only edits the change text, without querying svn. Make sure your reviewer information is accurate. It can be helpful to include a comment after the reviewers name containing the mail Message-ID for the reviewer's approval, or if approval is given some other way to note that. 8. To submit your change, invoke % svn-commit 9. Finally, update any Jira entries for bugs that are fixed by your change. Note the svn revision number from svn-commit. Run svn log -v -r and paste the output into Jira as the comment when resolving the bug. Also update the Fixed in Change# field with your svn . DETAILS Change descriptions in progress are stored in $SVNCHANGES. If you do not define and create $SVNCHANGES, it will be defined and created for you. These commands rely on the shell variable $OL_CHANGE_NAME, which is set by svn-newchange. The "change name" is the name of the directory in $SVNCHANGES which contains the change description. It looks like 20061013-ben-X where X is a uniquifying letter or number. The shell variable $EDITOR is used to determine the editor to use for editing your change description. All svn commands operate on the current directory, the contents of the current directory, and all descendants of the current directory, unless otherwise specified. This allows you to easily have different changes in play simultaneously in different directories of your workspace, but it also means that you must create your change in a directory that is an ancestor of _all_ the files involved in the change. Making your change at the root of your workspace is always safe. To create a new change, do $ svn-newchange which will create a new change description in $SVNCHANGES and set $OL_CHANGE_NAME. [*] To edit an existing change, do $ svn-editchange [] which will edit the change with the editor specified in $EDITOR. If is not given, $OL_CHANGE_NAME will be used (thus editing the most recent change), if there is no change in progess, a new change will be created. To send changes for review: $ svn-review or $ svn-review This makes the patch available in subversion, within the openlaszlo/patches directory, ie, http://svn.openlaszlo.org/openlaszlo/patches/20061013-ben-X.tar Note that this command checks your change in as a proposed change to the patches directory, for the purposes of review; it does not check in your code to the source tree itself. On the mac, this will open a message in Mail. On other platforms, it will echo the change on standard out, which you can pipe to your mail program of choice, or cut and paste (or dig into the code and make calling the mailer work for your platform). To apply a change from another developer $ cd $LPS_HOME $ curl -O http://svn.openlaszlo.org/openlaszlo/patches/$PATCH_NAME $ tar xvf $PATCH_NAME $ $PATCH_NAME/apply.sh (Note that the apply.sh technology is weak. It is sometimes better to simply untar the $PATCH_NAME/files.tar into your directory.) To back out a change you applied, either $ svn-unapplychangepackage which is really just "apply this patch in reverse", equivalent to $ patch -p0 -R -i difffile To commit $ svn-commit or if you've got your change message in a file you're managing $ svn-commit What's out? $ svn-pending prints a list of local un-committed change descriptions. Recommended practices Occasionally explicitly clean up stale un-committed changes in $SVNCHANGES. --- [*] Note that when you create a change description, the output of `svn status` is used to create the list of files associated with the change. You can edit this list (to delete files you do not want to check in), and the tools will respect your wishes (all of the other tools are driven off the list of files in your change description). As a consequence of this, if you modify or add more files _after_ you create your change description, they will _not_ be part of your change. This can be useful if you are working on more than one change at a time. If you want to add files to your change, run `svn status` manually and then edit the change description and add the additional files from the output.