Subversion Integration Functional Specification

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?

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] shows content changes
svn status lists local folder changes
svn status --show-updates update preview that contains remote changes
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 followed by a few SPACEs to see all repository changes
svn update get repository changes
[nested edit-compile-debug cycle]
[nested diff] svn diff | more followed by few SPACEs to see all local changes UC-5.5
svn add ... , svn remove and svn move
svn resolved ...
svn revert ... UC-5.6
svn propset ...
svn commit -m "Message" apply local changes to repository
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 producing read only BASE file (no local changes) content to console
svn log $FILE_NAME producing long output to console
[nested diff] svn diff -r $R1:$R2 [$FILE_NAME] for historical changes
svn cat -r $REVISION $FILE_NAME show file as of given repository revision.
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.

Create Branch

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

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 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
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 observing results manually investigating rejects
cvs diff > my.patch for changes relative to local file, svn diff $URL $URL2 > my.patch for arbitrary changes in history
diff > my.patch for arbitrary even non-versioned structures 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.

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.
covered by commit task
blame (praise, annotate, ann)
covered by editor blame bar
covered by history view
checkout (co)
covered by checkout wizard (except date range and nonrecursive option)
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
covered by Import wizard
partially covered by editor blame bar
list (ls)
covered by repository browser
covered by history browser TODO --stop-on-copy option
covered by Merge task TODO --dry-run
covered by commit task
move (mv, rename, ren)
Note: this subcommand is equivalent to a 'copy' and 'delete'.
integrated with conflict resolver and commit task
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)
propget (pget, pg)
covered by properties editor
proplist (plist, pl)
covered by properties editor
propset (pset, ps)
covered by properties editor and commit task
A newline separated list of file patterns to ignore.
Keywords to be expanded.
If present, make the file executable.
One of 'native', 'LF', 'CR', 'CRLF'.
The mimetype of the file. A mimetype beginning with 'text/' (or an absent mimetype) is treated as text. Anything else is treated as binary.
A newline separated list of module specifiers.
unsupported; --revprop commit date
unsupported; --revprop commit author
unsupported; --revprop commit message
There are available common options:
force operation to run
enable automatic properties
disable automatic properties
All of them are unsupported by IDE task actions.

See Also

Teepee project - NetBeans Subversion integration
Jihlava project - NetBeans CVS Integration
Petr Kuzel on January 9th 2006
TODO to be discussed ...

Project Features

About this Project

VersionControl was started in November 2009, is owned by tpavek, and has 105 members.
By use of this website, you agree to the NetBeans Policies and Terms of Use (revision 20160708.bf2ac18). © 2014, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo
Please Confirm