subversion: Subversion Integration Functional Specification

HOME > Community > Projects > subversion

Subversion Integration Functional Specification

This document describes planned functionality defined by requirements and use cases ("UC-#") and it forms a base for UI specification that should define the best UI for described tasks.

Target Audience

Experienced Subversion users, please read carefully and try to find out unsupported Subversion commands (or command arguments) that would block you from using implementation fullfilling this specification.

The document assumes basic experience with NetBeans 5.0 CVS support.

Note: The paper uses CVS terminology: branch, module, ... instead of the Subversion folder because it highlights folder function.

Note: The paper uses $-string notation for variables that depend on context. $-string name suggests what value is expected.

Summary of Requirements

Quick Setup
Update-Edit-Commit Workflow Integration
Integration with IDE concepts Projects ("PI"), Filesystems ("FSI"), Refactoring ("RI") and Editor ("EI")

Tasks Concept

A task oriented approach is chosen as the primary wheel. Tasks that integrate with daily IDE user workflow, map to multiple versioning system commands, or suggest the best practices stands for the IDE added value. Furthermore usability criteria dictate that the IDE must primarily support daily and error prone (setup) tasks. The tasks selected here are based on use cases document.

Setup Tasks

This covers the UC-1 Get NetBeans Project from Repository and UC-2 Get Sources from Repository use cases. Repository init (e.g. svnadmin --fs-type fsfs create /data/repository/svnfs) is left on aministrator.

Checkout project from the repository with the $URL link, $MODULE and $BRANCH into $LOCAL_WORKING_DIR. TODO authentication?

cd $LOCAL_WORKING_DIR

svn checkout $URL/$MODULE/$BRANCH

The above example assumes the standard repository layout with a dedicated branches/ folder for branches.

Supported repository access schemas are svn:, svn+ssh: http:, https:, file:.

The IDE supports out-of-box svn+ssh:, SSHv1 and SSHv2 schema. All remote schemas support firewall tunneling via SOCKS and HTTP proxy servers.
The IDE detects command failures caused by network connection or invalid authentification and suggests retrying (with modified password, proxy, ...) or let's the user cancel the action.
PI: The IDE automatically detects checked out NetBeans project(s) or guides through new project(s) setup from checked out sources.
The IDE recognizes existing (externally) checked out sources (working directories).
The IDE provides a visual repository structure browser, ideally recognizing NetBeans projects in the repository.

Diff Tasks

This covers UC-5.5 Viewing Changes use case.

Diff is used to observe repository and local changes at folder, file content and file properties level. This is a part of several other tasks.

svn diff [parameters that depends on situation]

svn status

svn status --show-updates

The IDE provides correct parameters if invoked from another task. See [nested diff] remarks below. Note: the IDE can actually do checkout/cat and then use build-in diff.

The IDE integrates (flat) folder content structure diff (a Subversion view) showing modified, added and removed files with visual diff that navigates through (multiple) file content differences. The visual diff shows sub-line differences such as block indentation and != vs == changes in long lines.

EI: While comparing with local files, it can be edited (removing debugging info, updating comments, ...).

The IDE diff can support additional comparison sources:

any file with an active editor
editor selection with clipboard content
arbitrary even unversioned file structures (pure diff)

Diff output can be saved as a patch file in context or unidiff format.

Update-Edit-Commit Cycle Tasks

This covers UC-4 Synchronize and UC-5.6 use cases.

[nested diff]

svn diff -r BASE:HEAD | more

svn update

[nested edit-compile-debug cycle]

[nested diff]

svn diff | more

svn add ...

svn remove

svn move

svn resolved ...

svn revert ...

svn propset ...

svn commit -m "Message"

The IDE Update and Commit action can be invoked from the diff view to apply (reviewed) changes.

The IDE Commit action assists with scheduling intended actions (add with options, ignore, remove, resolved, commit) then performs commit into repository.

FSI, RI: detect new and removed files and auto-suggest these for scheduling. The IDE catches rename refactorings and maps them to svn move.

PI: The IDE detects project dependencies and works in narrowed context covering actual project and projects it depends on.

PI: Support for before/after commit plugins (project target):

unit test invocation
bug tracking system integration
textual commit output

The IDE can map some system properties such as svn:ignore to dedicated action.

Source Archaeology Tasks

This covers UC-5.7 Understand Source use case. TODO improve UCs.

svn blame $FILE_NAME

svn log $FILE_NAME

[nested diff]

svn diff -r $R1:$R2 [$FILE_NAME]

svn cat -r $REVISION $FILE_NAME

EI: The IDE provides blame action showing results directly in the editor. Editor lines are side-by-side annotated by author, date, and commit message.

EI: For deeper investigation (see overwritten context), the blame sidebar can show diff for: current selection, entire file, or all changes in the same commit in context (package, whole project, ...).

PI: The history view provides a searchable changelog (arbitrary range) at project/folder level with the possibility to descend into file diffs.

Typical actions for found change:

rollback
merge into branch
export diff patch

Project Branching Tasks

Subversion models CVS branches and tags using copies.

Tag Project

This covers UC-5.4 Tag use case.

svn copy $REPOSITORY/$MODULE/tags/$SYMBOLIC_TAG

Create Branch

This covers UC-5.1 and UC-5.2 use cases.

svn copy $REPOSITORY/$MODULE/branches/$SYMBOLIC_TAG

For standard repository layout, the IDE can automatically consider tags/ folder entries as tag names and branches/ folder entries as branch names eliminating the need to specify the whole repository URL.

Switch to Branch

XXX missing use case?

Either checkout to new location or update sources in exiting location. Updating an existing location can cause problems if the user strictly follows the standard workdir layout (i.e. tags/, branches/) because it breaks the layout.

svn switch $REPOSITORY/$MODULE/branches/$SYMBOLIC_TAG

svn checkout $REPOSITORY/$MODULE/branches/$SYMBOLIC_TAG

Merge With Branch

This covers UC-5.3 use case.

Subversion does not track merges, so the user must manually avoid conflicts caused by re-applying the same change. A merge range should start from the last merge range end.

svn propget merge-last-$SYMBOLIC_TAG

svn merge $REPOSITORY/$MODULE/branches/$SYMBOLIC_TAG@$merge-last-$SYMBOLIC_TAG $REPOSITORY/$MODULE/branches/$SYMBOLIC_TAG

svn propset merge-last-$SYMBOLIC_TAG $REPOSITORY_REVISION_AT_MERGE

The IDE can use homeborn merge tracing and suggest to the user what revisions have already been accepted.

The IDE allows a preview [nested diff task].

The IDE could replace a built-in Subversion merge with a visual tool, giving the developer manual control over the process (see also patch), bypassing Subversion auto-merge.

The IDE can suggest a commit message "Merge: URL1 -r $START:$END into URL2".

Apply and Produce Patch

This covers UC-5.8 and UC-5.9 use cases.

patch -p $RELATIVE_STRUCTURE_OFFSET < desired.patch

cvs diff > my.patch

svn diff $URL $URL2 > my.patch

diff > my.patch

TODO How to create/apply diffs that contain properties changes?

The IDE provided a patch file and a target folder/file must correctly determine the structure offset.

A patch can be applied visually giving the developer manual control over the process including conflict resolution (in merge).

Patch producing is integrated with IDE diff task and support tree structure changes (new and deleted files).

Put Project under Version Control Task

This covers UC-3 use case.

Create a new versioned workdir covering project subtree. Then add recursively the whole project content.

cd $LOCAL_WORKING_DIR

svn import @URL

The IDE should have support for multi-rooted projects import.

Subversion Commands

This section lists all Subversion commands and pairs them with IDE Subversion tasks.

add

covered by commit task

blame (praise, annotate, ann)

covered by editor blame bar

cat

covered by history view

checkout (co)

covered by checkout wizard (except date range and nonrecursive option)

cleanup

unsupported, it looks like restore after unclean power-down command

commit (ci)

covered by commit task

copy (cp)

covered specialized tag and branch copying, TODO WC->WC, URL->URL

delete (del, remove, rm)

PATH delete covered by commit task, direct repository delete unsupported

diff (di)

covered by diff view TODO --notice-ancestry option

export

unsupported

import

covered by Import wizard

info

partially covered by editor blame bar

list (ls)

covered by repository browser

log

covered by history browser TODO --stop-on-copy option

merge

covered by Merge task TODO --dry-run

mkdir

covered by commit task

move (mv, rename, ren)

Note: this subcommand is equivalent to a 'copy' and 'delete'.

resolved

integrated with conflict resolver and commit task

revert

covered by Revert modification task

status (stat, st)

covered by Subversion view TODO properties

switch (sw)

covered by Switch action; --relocate special module such as CVSROOT chooser

update (up)

covered by Update and Merge actions

propdel (pdel, pd)

covered by properties editor and commit task TODO --revprop

propedit (pedit, pe)

unsupported

propget (pget, pg)

covered by properties editor

proplist (plist, pl)

covered by properties editor

propset (pset, ps)

covered by properties editor and commit task

svn:ignore: A newline separated list of file patterns to ignore.
svn:keywords: Keywords to be expanded.
svn:executable: If present, make the file executable.
svn:eol-style: One of 'native', 'LF', 'CR', 'CRLF'.
svn:mime-type: The mimetype of the file. A mimetype beginning with 'text/' (or an absent mimetype) is treated as text. Anything else is treated as binary.
svn:externals: A newline separated list of module specifiers.
svn:date: unsupported; --revprop commit date
svn:author: unsupported; --revprop commit author
svn:log: unsupported; --revprop commit message