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
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
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 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:
|
Diff output can be saved as a patch file in context or unidiff format. |
Update-Edit-Commit Cycle Tasks
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):
|
The IDE can map some system properties such as svn:ignore to dedicated action. |
Source Archaeology Tasks
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:
|
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.
or
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 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.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
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
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
- 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
- --force
- force operation to run
- --auto-props
- enable automatic properties
- --no-auto-props
- disable automatic properties
See Also
Teepee project - NetBeans Subversion integrationJihlava project - NetBeans CVS Integration
Petr Kuzel on January 9th 2006
TODO to be discussed ...