-- aerdemir 2013-10-06 16:40:30 This page uses Open Knee - Generation 1 repository architecture as an example. Open Knee - Generation 1 is now branched under the folder _gen1 at the root of the source code repository. Any information provided in here is applicable to get accustomed to the use of Subversion.
The project source code repository is a centralized repository based on Subversion. It is intended to facilitate collaborative development of software, data analysis code, and models. In this page, the team members can find brief instructions to facilitate their use of the repository within the context of project requirements. Members of the project have full permissions to access the repository and change it. Appropriate links are provided for more detailed help on Subversion.
It is IMPORTANT for team members to use the source code repository, because
- it allows concurrent and collaborative development of software and/or model
- all source code editing is under version control:
- mechanisms are implemented to resolve conflicting changes,
- it is always possible to revert (undo) changes;
- code and model development activities of individual team members and the whole project are clear and accessible by all team members and potentially by everyone:
- accurate acknowledgement of activities,
- facilitated dissemination;
- mature versions of the code and models can be provided as release versions.
Contents
Repository Location
Browsing
Project repository can be "viewed" online using any web browser at
https://simtk.org/websvn/wsvn/openknee/
The same area can be browsed by accessing the 'Source Code Repository' section under the 'Advanced' link at project site. General public has read access only, whereas being a team member is necessary to have full access privileges. While online browsing is useful to understand repository structure and to quickly view some files and revision history, team members who want to work on the files/folders should utilize a Subversion client for full access.
Full Access with Subversion Client
Repository can be accessed through a Subversion client, which will allow team members
- to make local copies of the whole repository (or its subfolders)
- to update their local copies with most recent versions
- to provide their changes back to the repository
For these purposes, the team members should direct their Subversion client to
https://simtk.org/svn/openknee
A variety of clients can be used to interact with the repository. A detailed list can be found in http://en.wikipedia.org/wiki/Comparison_of_Subversion_clients. Some useful clients with graphical interfaces include but not limited to
Repository Organization
The repository contains a dynamic and collaborative model development environment. While there are not any rigid rules on the organization of content, a few guidelines may help team members to start contributing based on their role and activities in the project. A proposed outline for the repository structure of Open Knee(s) - Generation 2 is provided below.
. |-- app: applications illustrating scientific and clinical use cases |-- aux: files and projects to support collaborative work | |-- cloud (or cld): files and projects to support cloud computing infrastructure | `-- febio (or fea): files and projects to support simulation software development |-- doc: general purpose documents | `-- img: general purpose images |-- _gen1: Open Knee - Generation 1 |-- license.txt |-- oks: Open Knee(s) models, Generation 2 development | `-- 001: specimen folder | |-- dat: specimen-specific data | | |-- anatomy (or ant) | | | |-- geometry (or geo) | | | |-- images (or img) | | | |-- mesh (or msh) | | | `-- registration (or reg) | | `-- mechanics (or mch) | | |-- joint (or jnt) | | |-- registration (or reg) | | `-- tissue (or tis) | |-- doc: specimen-specific documents | |-- sol: specimen-specific solutions to test simulations | `-- src: specimen-specific models and scripts |-- readme.txt `-- utl: files and projects to support Open Knee(s) utilities
The main outline of the repository structure for Open Knee - Generation 1 is illustrated below.
. |-- dat: data folder |-- doc: documentation folder |-- sol: solution folder following data analysis or model simulations |-- src: source code related to data analysis or modeling |-- license.txt `-- readme.txt
Details of creating new folders in the repository and working with repository content are described below. Appropriate links to the individual directories or files should be provided in relevant wiki pages. There is no right or wrong way to organize folder contents. As long as the folder is under version control, the overall structure and files can be changed without loss of information and continuity.
It is advised to subscribe to the mailing list openknee-commits Archives that can be found in the project site under 'Advanced->Mailing Lists', https://simtk.org/mail/?group_id=485. This will ensure that team members get e-mail notifications when others change the repository contents.
Subversion Terminology
- checkout
- making a local copy of the online repository by downloading the repository contents
- update
- updating the local copy of the repository; changes conducted on the local copies of files/folders are not overwritten
- add
- adding a file or folder under the local copy structure to the online repository definition;
- add recursively
- adding a folder under the local repository copy structure to the online repository definition; including all folder contents
- commit
- uploading files/folders (added or changed, if already existing) in the local copy to the online repository
- revert
- undoing changes conducted on the local copies of files/folders by downloading desired versions from the repository; overwrites the local files/folders
- diff
- compare two different versions of a text file; requires utility software for file comparison
Interacting with the Repository
Examples to interact with the repository are provided using RapidSVN, a Subversion client. You may want to download this client or any other, e.g. TortoiseSVN, to test Subversion functionality. Other clients work similarly using the same terminology.
Checking-Out a Local Copy
Using RapidSVN, a copy of an online repository (or parts of it) can be downloaded to the local computer from the menu:
Repository -> Checkout
Checkout process requires:
- the remote address (URL) of the repository
- destination directory on the local computer
- revision (by default it is set to latest)
By default, the local destination is added to the bookmarks for quick access and the repository contents are downloaded recursively. The example below illustrates checking out the whole repository.
The following examples shows how to check-out a single folder and its contents using the 'src' folder as an example. Contents are downloaded to a local directory on the user's computer in '/data0/openknee-src/':
Once checked-out, one can highlight the added bookmark to the local copy to see its contents:
To access (read & write) private sections of the repository, team members need to login using their SimTk account. If authentication is required, enter your SimTk username (IMPORTANT NOTE: use only lowercase letters!!! i.e. any upper case letters in your SimTk username should be made lower case!!!) and password. Login is also possible by selecting the bookmark of the local copy and the 'Login' command in the right-click menu.
Updating a Local Copy
Updating a local file or folder with a desired version in the repository can be done by selecting the file/folder and by following either of these steps:
Modify -> Update in the main menu
- Update command in the window following right mouse click
By default, the latest version will be used to update local files and folders recursively (including subfolders and files)
Always update the local copy with the most recent version of the repository before changing files. Another team member may have worked on the same files.
Committing Local Changes to Repository
After changing the files locally, the online repository can be upgraded by selecting these files (the local copies) and by following either of these steps:
Modify -> Commit in the main menu
- Commit command in the window following right mouse click
In the example below the local copy of the 'readme.txt' file was changed. The red shading of the icon indicates that the file is different than the last version updated from the repository. When this file is committed, the shading of the icon will turn white.
Creating Files and Directories
Files and directories can be created under the local copy of the repository as in daily computing. However, to ensure these files/folders are part of the repository, the remote (online) repository need to be informed about their existence. This can be accomplished by the 'Add' or 'Add recursive' operation. Note that this procedure only notifies the online repository that new files and/or folders will be part of it. To upload these, a 'Commit' operation should be followed, as described above.
In this example, a file was created under the main folder using a text editor on the local computer. When the folder is browsed using RapidSVN, a question mark can be seen in its icon. This indicates that this file does not belong to the repository yet.
Selecting this file and employing
Modify -> Add in the main menu, or
- Add command in the window following right mouse click
notifies the online repository that this file will be part of it. Consequently, the shading of the icon will turn red, with a '+' sign. A 'Commit' operation uploads the file to the repository.
Advanced Actions
Comparing Versions
Text files in the repository can be compared to previous versions using a 'Diff' tool. In the main menu at View->Preferences->Programs tab, a Diff tool needs to be defined (e.g. Meld).
Query -> Diff in the main menu
- Diff command in the window following right mouse click
Undoing Changes
If the changes in the local copy of the repository are undesired, and an undo operation is necessary, the 'Revert' functionality can be used
Modify -> Revert in the main menu
- Revert command in the window following right mouse click
By default, the latest version will be used to overwrite the local changes.
Moving Files or Folders
Modify -> Move in the main menu
- Move command in the window following right mouse click
Helpful Links
Software Carpentry: Useful information on software development for scientists, particularly on version control
RapidSVN Documentation: RapidSVN is a cross-platform, free and open source client for Subversion.
TortoiseSVN manuals: TortoiseSVN is an operating system specific, free and open source client for Subversion.