ABOUT

Svoboda Lab code related to device control and data acquisition lives on a Janelia Farm Subversion server.

The address for this code repository is at https://svn.janelia.org/svobodalab/software. It lives on the external network, and is thus available to users/developers outside Janelia Farm. It is maintained by Goran Ceric in Scientific Computing.

Below you can find information about how tagsand branches are employed in our development.

You can also find a SvobodaLab:bulletin board in which news related to Subversion is posted.

Tags (Release Versions)

As per the Subversion standard, release versions are stored in the tags subdirectory of this repository.

The history of ScanImage releases, as well as the full release of "Generation 1" software (includes ScanImage V3.0 and Physiology), was recreated in the repository. Each of these are available as folders within the tags subdirectory.

Current releases are tagged according to the following convention: <version #>.<major revision #>.<minor revision #>[SvobodaLab:.<patch #>]. Versions refer to major conceptual or codebase changes in the software. Major revisions refer to "significant" feature additions, bug fixes, and/or code changes. Minor revisions are less significant feature additions, bug fixes, code changes. This third number may increment on the time-scale of days. The fourth number appears only when changes are made to correct or improve a previous version, in cases where an upgrade is not feasible or practical for some users.

Releases are intended for now to contain the entire codebase, so everybody gets all functionality, regardless of whether they use it. Relases will be obtained by users en masse--working copies of each of the tagged releases will be made available on our website.  In certain cases where only a small number of files are affected, releases may also be made available as "patches" (note: not a subversion patch). Releases of this smaller number of files will be denoted by the release number, as described above, and the letter "p", appended at the end.

 Branches (Planned development organization)

As per the Subversion standard, the main development of the Svoboda lab control/daq software proceeds in the trunk subdirectory of the repository. Following the standard further, ongoing code changes and/or feature additions meeting some threshold of significance proceeds in folders within the root branches subdirectory of the repository.

It was agreed that the ability to commit changes to the trunk would be limited to the "core development team". This team is assumed to be communicating frequently among its members, and will make decisions along the way as to what ongoing work can be done directly as commits to the trunk, and which work should be done in one or more branches that would later reincorporated into the trunk via a merge procedure. Such decisions will take into account the extent to which efforts in the team are parallel (and thus likely to involve overlapping changes to the same files).

At present, the core development team consists of Tim O'Connor.
We refer to developers not on the core development team as "satellite developers". Our convention is that these developers are not generally permitted to directly commit changes to the trunk. Instead, their development must proceed within folders existing in the branches subdirectory.

The following summarizes our envisioned procedure for satellite development along the branches: 

• The satellite developer will be continually growing the branch, by saving milestone changes in their work using commit commands.
• As the branch grows, satellite developers will generally want to incorporate changes occurring along the trunk in order to minimize differences between the codesets. This would be done by applying merge operations along the way. These merge operations should run a comparison "from" a previous revision on the trunk (i.e. the revision at branch formation or at last merge operation) "to" the head revision on the trunk. The changes should then be applied to a branch working copy. A good note should be kept regarding the revision number range of the merge, so that future merges run from the new starting point along the trunk.
• During branch development, the satellite developer may notice some changes that would be of immediate value to the trunk codeset, i.e. they may fix a bug that impacts trunk functionality independent of the branch. The subset of files/changes would be ascertained using a merge command, and applying them to a working copy of the trunk. These modifications would be rolled into a patch file created by Subversion. This file would be sent to the core development team for review, likely using the TortoiseMerge utility to ascertain the changes made to individual files. Any changes approved by the core development team would be applied to a trunk working copy and uploaded via commit commands.
• At various milestones along branch development, its features may be rolled into the main codebase using the merge functionality, comparing head revisions along the branch and trunk, likely with close collaboration between the satellite developer(s) and the core development team, in order to resolve any conflicts that may need to be resolved. In some cases, this may be accomplished via the patch file mechanism described above.
• In general, the merge operations for both immediate patches and branch milestones should involve comparisons of revisions along the branch history, as opposed to comparisons between the head revisions of the branch and trunk, following this advice. This may merit further discussion. For this reason, the merge history should be well-recorded in the log comments in order to identify revisions along the branch at which they occurred. Subversion does not presently track merge history (this is considered one of its leading shortcomings).
• The final version along the branch would be incorporated into the trunk via a merge procedure, most likely in close collaboration with the core development team as above. The directory in the branches subdirectory may then be moved to an archive folder, so it no longer appears as an active project.

We have not yet determined a convention to distinguish between shorter branches, which are mainly created to result in minor revisions, and longer branches, which are primarily created to result in major revisions or version changes. It was agreed that such a convention would be useful, as it would allow one to quickly identify the ongoing development "threads" directly from the current repository structure.

SUBVERSION BULLETIN BOARD

POSTS to this bulletin board can be made by adding news in the Svoboda Lab space with the label "subversion".