Prerequisite Knowledge

Page Contents

1. Understanding of Subversion and the Software Collaboration Portal
   1. Common Subversion Commands
   2. Registering for Applications
2. Other

Understanding of Subversion and the Software Collaboration Portal

The NWS Software Collaboration Portal (SCP) is a centralized repository for locally developed software that is designed to be shared within the NWS. The NWS SCP is designed to foster collaborative development of software in addition to providing an efficient mechanism for discovering and sharing software and applications. The NWS SCP is moderated to provide a consistent structure for Wiki pages and a Subversion repository. The NWS SCP is comprised of wiki pages for each project/application, a ticket system to report problems or request enhancements with applications, a mechanism for users to register for applications, notifications for users to receive an email when applications are updated, and a Subversion software version control repository. The NWS Subversion Software Collaboration Portal (nwsscp) repository is located at https://vlab.noaa.gov/svn/nwsscp/. The NWS Redmine Project for your site is located at https://vlab.noaa.gov/redmine/projects/xxx where xxx is your site id. The Subversion repository provides a common and centralized database for software. The NWS Subversion repository for your site is located at https://vlab.noaa.gov/svn/xxx/ where xxx is your site id.

Subversion is a modern, network-aware version control system. A version control system is a system that tracks incremental versions of files and in some cases, directories over time. It also allows multiple people to access and modify the files simultaneously. At the core of the version control system is a repository, which is the central store of that system's data. The repository usually stores information in the form of a file system tree which is a hierarchy of files and directories. Users interact with the data in the repository by using a working copy. A Subversion Client (i.e., svn) commits (that is communicates the changes made to) any number of files and directories as a single atomic transaction. By atomic transition, either all of the changes are accepted into the repository or none them are. Each time the repository accepts a commit, this creates a new state of the file system tree called a revision. Each revision is assigned a unique natural number, one greater than the number assigned to the previous revision.

A subversion working copy is an ordinary directory tree on your local system, containing a collection of files. You can edit these files however you wish. Your working copy is your own private work area. Subversion will never incorporate other people's changes, nor make your own changes available to others, unless you explicitly tell it to do so. The suggested location for your offices' working copy is to make a svn_work directory in the /localapps/dev/ directory. After you've made some changes to the files in your working copy and verified that they work properly, Subversion provides you with commands to publish your changes to the repository. Each directory in your working copy contains a subdirectory named .svn. This is also known as the working copy's administrative directory. The files in each administrative directory help Subversion recognize which files contain unpublished changes, and which files are out of date with respect to others' work. For each file in a working directory, Subversion records:

• The revision your working file is based on
• A timestamp recording when the local copy was last updated by the repository

Common Subversion Commands

To get a working copy of a repository you must checkout a subtree of the repository. This is completed using the svn checkout command. For example, to create a working copy of your site's repository open a terminal and type cd /localapps/dev. Next type mkdir svn_work and type cd svn_work. Then type svn checkout https://vlab.noaa.gov/svn/xxx/ xxx_SiteRepo where xxx is your office's site ID. You will be required to log in with your NOAA email username (i.e., first.last) and password. If the user name that is supplied first by the terminal isn't your NOAA email username, type enter and then enter your NOAA email username and password at the respective prompts. Each directory and file that is in the repository will be printed out with an A on the left side (margin). An example for BOU is shown in the image below.

The letter As in the left margin indicate that Subversion is adding items to your working copy. When changes are made to a file in your working copy, you can use the svn commit command to publish that change to the repository. To use this command type svn commit -m, a message in quotes, and the path of the file. The message describes the change or changes you made. If another person at your office checked out your site's repository at the same time you did, then when you commit your changes to the repository the other person's working copy is left unchanged. In order for that person to see your changes, they will have to use the svn update command. To use the svn update command, type in terminal svn update after changing directories to the working directory of the repository, if not already in that directory. Each directory and file that is updated will be printed out with a U on the left side (margin). If you want to copy or move an item in the working copy of a repository, you should use svn copy or svn move instead of the Linux cp or mv commands.

Usually, prior to working on a project in your working copy of a repository you will want use the svn update command to bring your working copy into sync with the latest revision in the repository. The svn add command is used to add a file or directory to your svn working directory. The svn delete command is used to delete a file or directory from your svn working directory. The svn mkdir command is used to make a new directory in the working copy of the repository. The svn status command allows you to see an overview of the changes you've made since your last commit. Use this command prior to using the svn commit command, so that you know what will be added/removed to/from the repository. The svn status command outputs seven columns of characters, followed by several whitespace characters, followed by a file or directory name. Some of the most common codes that the svn status command outputs are:

• ? item
  • The file, directory, or symbolic link item is not under version control.
• A item
  • The file, directory, or symbolic link item has been scheduled for addition into the repository.
• C item
  • The file item is in a state of conflict. This means that changes received from the server during an update overlap with local changes that you have in your working copy (and weren't resolved during the update). You must resolve this conflict before committing your changes to the repository.
• D item
  • The file, directory, or symbolic link item has been scheduled for deletion from the repository.
• ! item
  • The file, directory, or symbolic link item has been deleted but is still in subversion.
• * item
  • The file directory, or symbolic link item has been changed by someone else and your file or directory is not up to date with the repository.

If you pass a specific path to svn status, you get information about that item alone. The svn log command shows log messages with the date and author information attached to each revision and which paths changed in each revision. The svn list command displays the files in a directory for any given revision. The svn export command is used for a one-time download of a directory or file from a repository. It is especially useful for retrieving a single file from a repository.

For more information on Subversion look at the Subversion Reference Sheet in the Appendices References section of this curriculum.

Registering for Applications

Your office should register for all applications on the SCP that are used at your site. To register, just click on the Register link on the application's Wiki page (upper-left below page title). At least one person from your site should "Watch" (click the Watch button in the upper left-hand corner) the Wiki pages of all of the applications on the SCP that are used at your site to receive notifications from the developer. This person will receive an email if the page gets changed. A lot of application Wiki pages include a "Subscribe to Issues" checkbox near the top of the page. When a member of your office clicks that checkbox for a particular application, that person will receive email notifications for any new or updated tickets for that application.

For more information on the NWS SCP and Subversion click here.

Other

All GFE Focal Points need to join the AWIPS Community on VLab.