Introduction

ISSM is hosted on an svn repository (subversion) for collaborative development. To use ISSM, you checked out the latest revision from the repository.

Checking file status

To see the current status of your file for a given directory:

svn status -u

You will see a list like:

M       test-file.txt
*       test-file2.txt

• M means that your version of test-file.txt is different than the current one in the repository (you have modified the file).
• * indicates that test-file2.txt is out dated (a new version has been pushed to the repository)
• ? indicates that this is a new file that is not in the repository
• ! means that the file is in the repository but is not present in your local trunk

Updating

Before any development, or before committing new changes, you have to update:

cd $ISSM_DIR
svn update

Resolving conflicts

Most of the time, svn does a good job at merging local modifications and new version of a given file. But... if the same line is both (1) locally modified and (2) changed on the new version, you will have a conflict. The best way to deal with conflicts is to FIRST add an editor to your ~/.bashrc:

export SVN_EDITOR="/usr/bin/vim"

and whenever there is a conflict, use the option e (edit). You will have to resolve the conflict manually. If you have a conflict and you don't know what to do for any reason, use option p (postpone). Then, manually edit the file (You will need to remove some of the stuff svn added to have both your changes and the new svn version, and a line of equal signs ============ separates both version). Once you are done use:

svn resolve --accept=working filename

Committing changes

When you check in changes (through svn commit), make sure that you commit all the modified/new files all at once, in one single commit. We want each version of trunk to compile and work, and committing one file at a time will break the code (it will break jenkins and if while debugging we revert to an older version of the trunk, it may not work if it was an intermediary commit). So make sure to commit everything in one single commit.

In order to check in your changes, you will need to run the svn commit command.

1. First, make sure that you are up to date, and your changes make sense.
2. Add your new file(s) to svn using svn add filename for all the new files and svn delete filename for the file that are not needed anymore (Note: the repository won't change until you enter an svn commit command)
3. You can commit (either one single file, a directory, or a list of files) using the following command:

   svn commit -m "CHANGE DESCRIPTION" filelist
   

the change description must start with one of these three letters:

• CHG: you just changed the code, did not fix a bug or did not add a new functionality
• NEW: you added a new capability
• BUG: you fixed a bug

WARNINGS:

• do not ever (EVER) commit from trunk-jpl without specifying the file list (you will end up checking in unwanted files in externalpackages or tests)
• do not ever (EVER) commit anything on trunk
• after you commit, check jenkins: ​https://ross.ics.uci.edu/jenkins/

Before Committing

Executables

Files intended for execution, including scripts, must have the correct permissions in order to be able to be run. Set permissions with,

sudo chmod 755 <file>

before committing to ensure that other users who check out a copy can execute the file, as intended, without having to first set permissions on the file locally.

macOS Extended File Attributes

On macOS, running ls -la in a Terminal may reveal one or more files that have extended attributes, denoted by '@' in the rightmost field. Extended attributes store extra, potentially personally identifiable information (i.e. the author's name). If you are developing on a Mac, it is important to remove such information from files before committing.

To remove all extended attributes on a given file, run,

xattr -c <file>

To remove all extended attributes on all files in a directory, run,

xattr -c $(ls <path>)

To remove all extended attributes on all files in the ISSM directory, recursively, run,

for file in $(find $ISSM_DIR -not \( -path '*/\.*' -prune \)); do if [[ ! $file = "." ]]; then xattr -c $file; fi; done

Correcting Permissions and/or Extended Attributes on Files That Have Already Been Committed

If you have committed a file with incorrect files permissions or unwanted extended attributes, you must,

1. Copy the file to a temporary location (copying and pasting to a new text document will suffice).
2. Delete the file from the repository.
3. Create a new file with the same name in your local copy of the repository.
4. Copy the contents of the original file into this new file.
5. Modify permissions and/or extended attributes on the new file.
6. Commit the new file to the repository.