CVS Integration Functional Specification
The document describes planned functionality defined by
requirements and
use cases
and it forms a base for
UI specification
that should define best UI for described
tasks.
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
Task oriented approach is chosen as primary wheel. Tasks that integrates
with daily IDE user workflow, maps to multiple versioning system commands
or suggests best practices stands for IDE added value. Furthermore usability
criteria dictate that IDE must primarily support daily and error prone (setup)
tasks. The tasks selection here is based on
use cases document.
Remaining use cases are left on experienced users judgment giving them 1:1
mapping to versioning system commands. This group of commands is not deeply
discussed here. See NB 4.1 generic CVS integration UI that takes commands approach
(however there are traces of task approach: add with automatic commit, checkout with open results action).
Setup Tasks
Covers
VCS-1 and
VCS-2 use cases.
Checkout project from repository having $CVSROOT link, $MODULE and $BRANCH into
$LOCAL_WORKING_DIR.
cd $LOCAL_WORKING_DIR
cvs -d $CVSROOT login
cvs -d $CVSROOT checkout [-r $BRANCH] $MODULE
Required connection types are :pserver:, :ext:
and :fork: (:local: over C/S protocol) methods.
|
IDE suppors out-of-box pserver, SSHv1 and SSHv2 connection methods with optional
firewall tunnelling via SOCKS and HTTP proxy servers.
|
|
IDE checks network connection and user's login. This check is done for all subsequent
versioning system operations. Failing to assure connection is up IDE suggests
off-line mode.
|
|
PI: Allow user to detect NetBeans project(s) or setup new project(s) from checked
out sources.
|
|
IDE remembers local workdir roots and enables versioning support for descendants.
User can explicitly enlist local workdir roots to enable IDE versioning for already
existing checked-out sources.
|
Diff Tasks
Covers
VCS-5.5 use case.
Diff is used to observe repository and local changes at folder or file content level.
It's a part of several other tasks where invocation differs in
parameters IDE passes to it.
cvs diff [parameters that depends on situation]
cvs -n update it's more compact form of cvs status
|
IDE provides correct parameters if invoked from another task. See [nested diff]
marks bellow.
|
|
IDE integrates (flat) folder content structure diff (a Sync view) showing modified,
added and removed files with an action that navigates through all/selected file
content differences.
|
|
IDE's build-in visual diff detects sub-line differences such as blocks indentation and
!= vs == changes in long lines.
|
|
EI: If comparing with local file it optionally allows change editing
(removing debugging info updating comments).
|
IDE diff can support additional comparison sources:
- any file with active editor
- editor selection with clipboard content
- arbitrary even unversioned file structures (pure diff)
|
|
Diff output can be saved as patch file.
|
Update Commit Cycle Tasks
Covers
VCS-4 and
VCS-5.6 use case.
Keep is as simple as on command line:
[nested diff] cvs diff -r HEAD | more followed by few SPACEs to see all repository changes
cvs update get repository changes
[nested edit-compile-debug cycle]
[nested diff] cvs diff | more followed by few SPACEs to see all local changes 5.5
cvs add ... and cvs remove
rm ...; cvs update ... 5.6
cvs commit -m "Message" apply local changes to repository
|
IDE Update action supports remote changes diff preview and
allows to apply selected changes.
|
|
IDE Commit action assists with reviewing local changes diff,
scheduling intended actions (add, ignore, remove, commit) and finally
commit local changes to repository.
|
|
FSI, RI: detect new and removed files and auto-suggest these for scheduling.
|
|
PI: IDE detects project dependecies and works in narrowed context covering
actual project and projects it depends on.
|
|
Bug Tracking system integration: IDE can authomatically create
patch files (diff output) and simple commit output pasteable/attacheable
into related issue.
|
Source Archaeology Tasks
Covers
VCS-5.7 use case.
cvs annotate $FILE_NAME producing readonly full file content to stdout
cvs log $FILE_NAME producing long output to stdout
[nested diff] cvs diff -r $R1 -r $R2 $FILE_NAME for single file changes
[nested diff] cvs diff -D $T1 -D $T2 for all related changes
|
EI: IDE provides editor action showing results directly in context of current
editor caret position. Results contain both originator and commenting commit
message.
|
|
EI: Source history can be integrated right with editor view under
a History tab.
|
|
For deeper investigation IDE allows to browse commented history diff for: current
selection, whole file or all related changes in context (package, whole project, ..)
done by the same commit. As input it can parse commit output pasted in related issue.
|
Project Branching Tasks
Project Tagging
Covers
VCS-5.4 use case.
Create Branch
Covers
VCS-5.1 and
VCS-5.2 use cases.
Best practice is that user marks branch root, then updates to it, following by
creating branch and updating to it. On command line it forms 4 commands.
cvs tag $BRANCH_ROOT
cvs update -r $BRANCH_ROOT
cvs tag -b $BRANCH
cvs update -r $BRANCH
|
In IDE it can be one high level action. IDE uses naming
convention for branching point ($BRANCH_ROOT) naming.
|
Work on Branch
XXX missing use case?
Either checkout to new location or update sources in exiting location.
cvs update -r $BRANCH_OR_TAG
Merge With Branch
Covers
VCS-5.3 use case.
Branch merging needs careful tagging to avoid change duplicates merging.
On subsequent merges range starting from last merge point must be selected.
cvs update $SOURCE-BRANCH
cvs tag NB_$SOURCE-BRANCH_to_TARGET-BRANCH_sync(#)
cvs update -r $TARGET-BRANCH
cvs update -j NB_$SOURCE-BRANCH_to_TARGET-BRANCH_sync(#-1) -j NB_$SOURCE-BRANCH_to_TARGET-BRANCH_sync(#)
|
IDE can automatically tag (using reserved tag prefix NB_) and later
substitute previous merge points. It specially treats first merge where
branch point tag is used instead.
|
|
IDE allows preview [nested diff task] parameterized by range NB_$SOURCE-BRANCH_to_TARGET-BRANCH_sync(#-1) -j NB_$SOURCE-BRANCH_to_TARGET-BRANCH_sync(#).
|
|
IDE can replace build-in CVS merge with visual tool giving developer manual
control over process (see also patch) bypassing CVS auto-merge.
|
Apply and Produce Patch
Covers
VCS-5.8 and
VCS-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, cvs rdiff -r$R1 -r$R2 > my.patch for arbitrary changes
diff > my.patch for arbitrary even non-versioned structures
|
IDE having patch file and target folder/file must correctly determine structure offset.
|
|
Patch can be applied visually giving developer manual
control over process including conflict resolution (in merge.
|
|
Patch producing is integrated with IDE diff task.
|
Put Project under Version Control Task
Covers
VCS-3 use case.
Create new versioned workdir covering project subtree. Then add recursively whole project
content.
Using pure command line CVS it's rather tricky:
cd $LOCAL_WORKING_DIR
cvs -d $CVSROOT import $MODULE $VENDOR $BRANCH
cd ..
rm -r $MODULE
cvs -d $CVSROOT checkout $MODULE
|
IDE, having under control CVS C/P protocol, can post recursive add directly.
|
Pure 1:1 Versioning System Operations
These integrates with IDE too. They must respect actual logical view,
build-in ignore lists,
etc.
Petr Kuzel on Feb 15th 2005
TODO to be discussed by 17th Feb 2005.
