versioncontrol: Clear Case Support UI Specification

HOME > Community > Projects > versioncontrol

Clear Case Support UI Specification

Status: Work in progress...,

Abstract

This paper defines a user interface which lets the users to access the Clear Case functionality directly from the NetBeans IDE.

Main Menu

The main menu contains actions which can be invoked in various contexts (files, editor, search results. ClearCase view, ...).

Versioning > ClearCase 
    
   Checkout.../Undo Checkout...                      
   Reserve.../Unreserve...             
   Hijack/Undo Hijack
   Add to Source Control...    
   -----------------------------   
   Show Changes
   Diff 
   Update
   Merge...
   Checkin...    
   -----------------------------
   Export Diff Patch...   
   Apply Diff Patch...   
   -----------------------------   
   Label...
   -----------------------------
   Show Annotations
   View Revision...
   History   
   Version Tree
   -----------------------------
   Ignore
   Excude from Commit
   -----------------------------
   Show Properties      
   -----------------------------

File Status in the NB Clear Case support

There are several places in the NetBeans IDE (Projects View, Versioning View, Checkin dialog, Editor tabs, ...) where additional informations related to a files or folders type or its actuall local or remote state are vizualized.

This so called "status" value may be one from the following:

Status	Color	Status Name / Annotation	Description
up-to-date	Default	-	the file is up-to-date
Reserved Checkout	Blue	Reserved	a reserved checkout was performed
Unreserved Checkout	Blue	Unreserved	a unresered checkout was performed
Checkedout but removed / Loaded but missing	TODO: no idea	TODO: Checkedout but removed	the file was checked out/hijacked and locally removed. TODO - handle this like localy deleted?
Hijacked	Blue	Hijacked	the file was hijacked
Eclipsed	Grey, striked trough	Eclipsed	the file is eclipsed
View Private - To be added to source control	Green	New	the file is of a view private type but is supposed to be versioned - e.g. the user created a new java file in the IDE
View Private - Ignored	Grey	Ignored	the file is of a view private type and is supposed to stay like that for a long time or for ever

TODO - what about remote status values - only if the file is checked out be another user, or also remote changes like higher version, new, deleted etc.
TODO - another status values? - e.g. checked out but removed, loaded but missing, locked, [hijacked, nocheckout] etc.?

View Private Files in the NB Clear Case support

View private files visible in the IDE (not masked by NetBeans visibility settings) are handled like New or Ignored respectively:

There is a built-in logic which automatically renders files as ignored if they match some specific rules - e.g project private files etc.
If the Ignore New Files setting is selected then all view private files will get the "Ignored" status by default. All ignored files may be still added to source control by an explicit "Add to Source Control" user action.
If the Ignore New Files setting isn't selected and the built-in ignore logic doesn't apply for a view private file, then it will be handled like New (a source control candidate) and taken in count by the Versioning View or may be eventually automaticaly added to source control before a checkin in the Checkin dialog. Automatically ignored files may be still added to source control by an explicit "Add to Source Control" user action.

Ignore New Files	Built-in Ignore applies	Default Status	Add to source control by user action
On	Yes	Ignored	Yes
On	No	Ignored	Yes
Off	Yes	Ignored	Yes
Off	No	New	Yes

Projects Window

The Projects window allows the user to perform versioning commands on versioned projects, folders (containers) and files. A project is versioned if at least one folder in the project is versioned. A folder or a file is considered versioned if it is placed within a VOB.

The Projects window visualizes some Clear Case related information about a file or folder ("Status" - Checked out, hijacked, ...) as described in File Status in the NB Clear Case support. This "status" values are indicated by different colors of node labels. An additional text annotation is added to the files name if View/Show Versionig Labels is selected and the same (color and text annotation) are used in editor tab labels as well. Projects and folders have also icons which indicate that they are versioned and that they eventually contian files or forders which aren't up-to-date.

Project and folder icon badge colors and corresponding states:

No badge - project is not in a Clear Case VOB
TODO - do we have this? Black color badge - project is versioned and all files are up-to-date
Blue color badge - project contains new or modified files (Locally New or Locally Modified)

Figure: ClearCase File Name Colors in Projects Window

+---------------------------------------------------------+
| Projects                                                |
+---------------------------------------------------------+
| [a] My Java App                                         | (Project is versioned)
|  -- [j] Source Packages                                 | 
|  |   -- [p] <default package>                           | 
|  |   |   +- [c] MyClassInDefaultPackage.java            |
|  |   -- [e] com.mycompany.newpackage                    |
|  |   -- [pb] com.mycompany.petstore                     | (Contains files which are checked out & co.)
|  |       +- [b] Bundle.properties [Ignored]             | (Ignored)
|  |       +- [c] Main.java [Reserved]                    | (Checked out - Reserved or Unreserved, Hijacked eventually)
|  |       +- [c] Petstore.java                           | (Up to Date) 
|  |       +- [c] PetstoreApp.java [Eclipsed]             | (Eclipsed)
|  |       +- [c] AbstractPetstore.java [New]             | (View private to be added)    
|  |   +- [p] com.mycompany.petstore.api [Unreserved]     | (Checked out - Unreserved or Reserved eventually)
|  |   +- [p] com.mycompany.petstore.lib                  |
|  |   +- [p] com.mycompany.petstore.ui                   |
|  -- [t] Test Packages                                   |
|      +- [p] com.mycompany.petstore                      |
|      +- [p] com.mycompany.petstore.api                  |
|      +- [p] com.mycompany.petstore.lib                  |
|      +- [p] com.mycompany.petstore.ui                   |
| [a] My Java Lib                                         |
|  +- [j] Source Packages                                 |
|  +- [t] Test Packages                                   |
|                                                         |
|                                                         |
|                                                         | 
|                                                         |
+---------------------------------------------------------+

[a] - Versioned Project icon
[j] - Source Packages logical folder icon
[t] - Test Packages logical folder icon
[p] - Java Package icon
[e] - Java Package empty icon
[j] - Java File icon
[b] - Properties File icon
[pb] - Java Package icon with a blue badge indicating that the folder contains files which are checked out & co.

Contextual Menu: File Node

    
   Checkout.../Undo Checkout...                      
   Reserve.../Unreserve...          
   Hijack/Undo Hijack
   Add to Source Control...    
   -----------------------------   
   Show Changes
   Diff 
   Update
   Merge...
   Checkin...       
   -----------------------------   
   Label...
   -----------------------------
   Show Annotations
   View Revision...
   History   
   Version Tree
   -----------------------------
   Ignore
   Excude from Commit
   -----------------------------
   Show Properties      
   -----------------------------

Versioning View (Show Changes) Dialog

The Clear Case versioning view initially appears docked at the position of Output window. It may be opened either from the Window/Versioning/ClearCase menu or via the Show Changes action invoked on projects, folders or files.
If the window gets invoked from the Window/Versioning menu for the first time then - TODO: it has no context at all??? Otherwise it shows the status for the previous context (projects, folders, files).

The CC window shows the user a subset of project files that aren't up-to-date with the repository. Files and folders with the fololowing status will by listed:

Reserved checkedout
Unreserved checkedout
Hijacked
Checked out but removed / Loaded but missing
Eclipsed
New (View Private files to be added to source control)

Various status values may be renderd with a different color and font decoration, see also File Status in the NB Clear Case support

TODO - it is to decide what kind of remote information we want to show in the view

only checkouts made by another users
all possible remote changes like:
- checkouts made by another users
- remotely new or deleted files
- that a higher version for a files exists
- ...

Figure: the CC window showing one project after invoking the Show Changes action on JavaApplication project

    +---------------------------------------------------------------------------------------------------------------------+
    | Clear Case - JavaApplication1 (10 minutes ago)                                                                      |
    +---------------------------------------------------------------------------------------------------------------------+
    | [ All ] [ Local ] [ Remote ] [VP]   [ R ] [ D ]   [ C ]                                                             |
    |---------------------------------------------------------------------------------------------------------------------|
    |______________File________________|_______Status________________v_|_Branch_|________________Location_________________|
    | Main.java                        | Reserved                      | main   | JavaApplication1/src/javaapplication1   |
    | NewClass1.java                   | Unreserved/CHECKEDOUT by peter| main   | JavaApplication1/src/javaapplication1   |
    | NewClass2.java                   | Eclipsed                      | main   | JavaApplication1/src/javaapplication1   |
    | NewClass3.java                   | New                           | main   | JavaApplication1/src/javaapplication1   |    
    | Hijacked.java                    | Hijacked                      | main   | JavaApplication1/src/javaapplication1   |        
    | javaapplication                  | Reserved                      | main   | JavaApplication1/src                    |            
    |                                  |                               |        |                                         |
    +---------------------------------------------------------------------------------------------------------------------+

where:

Clear Case - title bar - shows the name of the objects (projects, folders, files) the Show Changes action was invoked on. The name pattern is Clear Case - <object-name>. If the Show Changes action was invoked on multiple objects then the title bar shows the number of objects: Clear Case - <TODO>
[All] - toggle button - if selected all files (local, remote) are shown in the table. If no changes are available then the No Local/Remote Changes text is centered in the table. Tooltip: Shows remote and local changes TODO - changes ? Always enabled.
[Remote] - toggle button - if selected only remote files are shown in the table. If no changes are available then the No Remote Changes text is centered in the table. Tooltip: Shows remote changes. Always enabled.
[Local] - toggle button - if selected only local files are shown in the table. If no changes are available then the No Local Changes text is centered in the table. Tooltip: Shows local changes since last update. Always enabled.
[VP] - toggle button - Show New (View Private) files - toggles on/off if New (View Private files) are to be shown in the table. Tooltip - "Show View Private Files" or "Hide View Private Files" eventually.
[R] - button - Refesh - e.g to get non local values - Tooltip "Refresh". Always enabled.
[D] - button - Diff - opens the NB diff view for all files from the view TODO - not sure how this work according to [All | Remote | Local]
[C] - button - Checkin - invokes the checkin action for all files from the view
Changes - table - shows all files which are checked out, hijacked, eclipsed atd.
- File - table column - shows the icon and file name. Rendered with different color depending on the files state. See also File Status in the NB Clear Case support.
- Status - table column - shows the files state. See also File Status in the NB Clear Case support
- Branch - table column - shows the files branch
- Location - table column - the files path in the VOB table starting from the top level versioned folder
- TODO decide what additional values (user, view, ...) should be shown for a file. Could be added to the table or be accessible via an action - e.g Describe
Contextual Menu: File Node
```
    Open
    -----------------------------
    Undo Checkout
    Reserve.../Unreserve...                      
    Add to Source Control...        
    -----------------------------
    Diff                          (default action)    
    Update    
    Checkin...    
    Add to Source Control        
    -----------------------------
    Show Annotations
    List History
    Browse History
    Browse Version Tree
    -----------------------------
    Exclude from Checkin          (Include in Checkin)    
    Ignore
    Show Properties    
```
History
TODO: - list hisotry, search history ...
Diff Window

The diff window shows the difference between files. TODO - folders ? It appears in the editor area.

Figure: Diff window showing the difference between the checked out revision of Main.java and its predecessor.
```
 
     -----------------------------
    / JavaApplication [ Diff ]  x \
    +---------------------------------------------------------------------------------------------+
    | [ N ] [ P ]  [ R ] [ C ]                                                                    |
    |-----------------------------+--------------+------------------------------------------------+
    | File                        | Status       | Location                                       |
    +-----------------------------+--------------+------------------------------------------------+    
    | Main.java                   | Reserved     | JavaApplication1/src/javaapplication1          |   
    | ...                         |              |                                                |
    +-----------------------------+--------------+------------------------------------------------+    
    |      Predecessor ver. 22                   |              Locally Modified                  |
    +--------------------------------------------+------------------------------------------------+            
    | Diff View                                  |                                                |
    |                                            |                                                |
    |                                            |                                                |
    |                                            |                                                |
    |                                            |                                                |
    |   (Diff view left Pane)                    |     (Diff View right Pane)                     |
    |                                            |                                                |
    |                                            |                                                |
    |                                            |                                                |
    |                                            |                                                |
    +---------------------------------------------------------------------------------------------+
        
```
where:
- N - button - Next Difference - scrolls the diff view to the next difference (cycles over all files). Keyboard shortcut is <ctrl-period>. Enabled if there is a next difference in the Diff View.
- P - button - Previous Difference - scrolls the diff view to the previous difference (cycles over all files). Keyboard shortcut is <ctrl-comma>. Enabled if there is a previous difference in the Diff View.
- R button - Refresh Diff - refreshes the diff of all files shown in the Diff window. Button tooltip is Refresh Diff. Always enabled.
- C - button - Checkin - invokes the checkin action for the files shown in the Diff window. Button tooltip is Checkin "<object-name>" where the object name is the same as object name shown in the title bar of diff window. Always enabled.
- File Table component - table - Shows a list with files and folders for which the Diff was invoked.
  - File - column - shows the files name. Colored depending on its status. See also File Status in the NB Clear Case support.
  - Status - column - gives the files status. See also File Status in the NB Clear Case support. Possible values are:
    - Reserved
    - Unreserved
    - Hijacked
    - Eclipsed
    - New
  - Location - column - the files path in the VOB
- Diff View component - Diff View - shows the actual difference between versions. Titles of the diff view panes indicate specific versions that are compared.
  - Diff view left Pane - shows the contents from the files predecessor. The title format is Predecessor ver. <predecessor-version>
  - Diff view right Pane - shows the contents from the selected file. The title format is Locally Modified
  See Diff Specification for more information how the differences between files are visualized.
Checkout dialog
May be opened for a single or multiple files selection.
```
   +-------------------------------------------------------------
   | Checkout <file/n files>
   +-------------------------------------------------------------
   | Specify the checkout message
   | +-----------------------------------------------------------
   | | This is not a checkout message.
   | | 
   | | 
   | |
   | +-----------------------------------------------------------
   | [x] Reserved
   | [x] Preserve the hijacked files contents
   |
   |                                   [Checkout] [Cancel] [Help]
   +-------------------------------------------------------------
```
where:
- Checkout message - textarea - contains the checkout message
- Reserved - checkbox - specifies if the checkout will be reserved, or not
- Preserve the hijacked files contents - checkbox - enabled if any hijacked file are selected for the checkout. Keeps the files contents.
- Checkout - button - checks out the files
TODO: - version to be checked out?
Cancel Checkout dialog
May be opened for a single or multiple files selection.
```
   +-------------------------------------------------------------
   | Undo Checkout for <file/n files>
   +-------------------------------------------------------------
   | Do you want to undo the checkout for the selected file(s)?
   | [ ] create .keep file to preserve contents
   |
   |                                       [Undo] [Cancel] [Help]
   +-------------------------------------------------------------
```
where:
- Create .keep file - checkbox - specifies if a backup copy should be created from the uncheckouted file
- Undo - button - will undo the checkout for the selected files
- Cancel - button - cancels the dialog
Reserve dialog
May be opened for a single or multiple files selection.
```
   +-------------------------------------------------------------
   | Reserve <file/n files>
   +-------------------------------------------------------------
   | Checkout message
   | +-----------------------------------------------------------
   | | This is not a checkout message.
   | | 
   | | 
   | |
   | +-----------------------------------------------------------
   |
   |                                    [Reserve] [Cancel] [Help]
   +-------------------------------------------------------------
```
where:
- Checkout message - textarea - contains the checkout message
- Reserve - button - switches the checkout type to Reserved
Unreserve dialog
May be opened for a single or multiple files selection.
```
   +-------------------------------------------------------------
   | Unreserve <file/n files>
   +-------------------------------------------------------------
   | Checkout message
   | +-----------------------------------------------------------
   | | This is not a checkout message.
   | | 
   | | 
   | |
   | +-----------------------------------------------------------
   |
   |                                  [Unreserve] [Cancel] [Help]
   +-------------------------------------------------------------
```
where:
- Checkout message - textarea - contains the checkout message
- Unreserve - button - switches the checkout type to Unreserved
Checkin dialog
May be opened for a single or multiple files selection. Shows a list with all files from the selected context.
```
   +--------------------------------------------------------------------------------
   | Checkin <file/n files>
   +--------------------------------------------------------------------------------
   | Checkin message                                                           [RM] 
   | +------------------------------------------------------------------------------
   | | :-)
   | | 
   | | 
   | |
   | +------------------------------------------------------------------------------
   |
   | Files to Checkin:                                                         [F] 
   | +----------------+------------+----------------------+-------------------------
   | | File           | Status     | Checkin Action       | Path 
   | +----------------+------------+----------------------+-------------------------
   | | Main.java      | Reserved   | Checkin              | .../src/Main.java
   | | NewClass.java  | New        | Add and Checkin      | .../src/NewClass.java
   | | Main.java      | Unreserved | Exclude from Checkin | .../src/Main.java       
   | | ...
   | +------------------------------------------------------------------------------
   | [x] Preserve modification Time
   | [x] Checkin even if identical to predecessor
   | 
   | Preparing Checkin ... [//////////////////____________________________________]
   |
   |                                                      [Checkin] [Cancel] [Help]
   +--------------------------------------------------------------------------------
```
where:
- [RM] - button - Recent Messages - open a dialog displaying a list with recent messages and lets the user pick one.
- Checkin message - textarea - contains the checkin message. If all to be checked in files where checked out with one distinct checkout message (empty messages don't count) then this one will be preselected in the field. Otherwise, if present, the topmost message from the 'Recent Messages' list will be taken. The same message is used for all files checked in from one dialog session.
- [F] - button? - Filter - allows the user to specify which files from the selection are listed in the Files to Checkin table. Possible selections are:
  - All files - this means that not only files the action was invoked over, but also children from folders will be listed (according to the flat/non flat logic)
  - Only selected files - lists only the files for which the checkin action was invoked.
- Files to Checkin - table - a list containing all files from the selected context which are supposed to be checked in.
  - File - column - the files name. Colored depending on its status. See also File Status in the NB Clear Case support.
  - Status - column - gives the files status. Possible values are:
    - Reserved
    - Unreserved
    - Hijacked
    - New - depends on the Ignore New Files setting. See also View Private Files in the NB Clear Case support.
    See also File Status in the NB Clear Case support.
  - Checkin Action - column - specifies how the file should be handled by the checkin action
    - Checkin - available if the file was checked out, or hijacked
    - Exclude from Checkin - available if the file was checked out, hijacked or is new (view private file).
    - Add and Checkin - available if the file is new (view private file).
  - Path - column - the files path in the VOB
- Preserve modification Time - checkbox - preserves the modification time of the file being checked in
- Checkin even if identical - checkbox - checks in the element even if the predecessor version is identical to the checked-out version. TODO: decide if otherwise a silent uncheckout should be performed or if the user should be annoyed with a popup (Uncheckout and keep walking / Cancel)..
- Preparing Checkin ... - progress bar - visible while the files list gets prepared.
- Checkin - button - checks in the files
Add to source control dialog
May be opened for a single or multiple files selection. Shows a list with all files from the selected context.
```
   +-------------------------------------------------------------
   | Add to source control 
   +-------------------------------------------------------------
   | Describing message                                      [RM] 
   | +-----------------------------------------------------------
   | | :-)
   | | 
   | | 
   | |
   | +-----------------------------------------------------------
   |
   | Files to Add:                                           [F]
   | +-----------+--------+--------------------------------------
   | | File      | Action | Path 
   | +-----------+--------+--------------------------------------
   | | Main.java | Add    | .../src/Main.java
   | | ...
   | +-----------------------------------------------------------
   | [ ] Suppress Checkout  
   | 
   | Preparing Checkin ... [//////////////////__________________]   
   |    
   |                                        [Add] [Cancel] [Help]
   +-------------------------------------------------------------
```
where:
- [RM] - button - Recent Messages - opens a dialog displaying a list with recent messages and lets the user to pick one.
- Describing message - textarea - contains the element description. Preselected with the topmost message from the 'Recent Messages' list. The same message is used for all files checked in from one dialog session.
- [F] - button? - Filter - allows the user to specify which files from the selection are listed in the Files to Checkin table. Possible selections are:
  - All files - this means that not only files the action was invoked over, but also children from folders will be listed (according to the flat/non flat logic)
  - Only selected files - lists only the files for which the checkin action was invoked.
- Files to Add - table - a list containing all to be added files
  - File - column - shows the files name. Colored depending on its status. See also File Status in the NB Clear Case support.
  - Action - column - specifies how the file should be handled by the "Add to ..." action
    - Add - add the file to source control
    - Exclude - do not add the file to source control
  - Path - column - the files path in the VOB
- Suppress Checkout - checkbox - if seletected the files won't be checked out after added to source control
- Preparing Add To... - progress bar - visible while the files list gets prepared.
- Add - button - Adds the files
Merge dialog
Can be opened only for a single file or folder selection. TODO
Label dialog
May be opened for a single or multiple files selection.
```
   +-------------------------------------------------------------
   | Label
   +-------------------------------------------------------------
   | 
   | Label:   [____________________________________] [Browse...]
   | Version: [________] (Empty means default)
   |           
   | [ ] Recurse
   | [ ] Replace
   | [x] Follow
   |                                     [Label] [Cancel] [Help]
   +-------------------------------------------------------------
```
where:
- Label - textfield - specifies the labels name
- Browse... - button - opens a list with all known labels from which the user may pick one
- Version - textfiels - specifies the version for which the label has to be set
- Recurse - checkbox - sets the label recursivelly for the whole subtree
- Replace - checkbox - Removes an existing label of the same type from another version of the selected file or folder
- Follow - checkbox - For any VOB symbolic link encountered, labels the corresponding target.
- Label - button - attaches the version label
Options Dialog
```
   +--------------------------------------------------------------------------------
   | ClearCase Options
   +--------------------------------------------------------------------------------
   | 
   | Cleartool executable path [____________________] [Browse...] 
   |     
   | View Private Files ------------------------------------------------------------
   |  [x] Add View Private Files to Source Control
   |
   | On-demand Checkouts -----------------------------------------------------------
   |  ( ) Disabled (manual chcekout required to modify files)
   |  ( ) Hijack
   |  ( ) Unreserved
   |      [ ] Fallback to Hijack
   |  (.) Reserved
   |      [ ] Fallback to Unreserved
   |      [ ] Fallback to Hijack
   |
   | Clearcase Status Labels -------------------------------------------------------
   |  Format [___________________________________________________] [Add Variable...]
   |
   | 
   | TODO - what else? 
   |                                                           [Add] [Cancel] [Help]
   +--------------------------------------------------------------------------------
```
where:
- Ignore new file - checkbox - if selected then newly created files won't be regarded like source control candidates. See also View Private Files in the NB Clear Case support.
- Cleartool executable path - textfield - specifies the cleartool executable path
- Browse - button - opens a file browser
Missing Cleartool executable Dialog
Opened when cleartool not in path and action invoked
```
   +-------------------------------------------------------------
   | Missing Cleartool Executable
   +-------------------------------------------------------------
   | The Cleartool Executable doesn't seem to be in your Path.
   |
   | Cleartool executable path [____________________] [Browse...] 
   |        
   |                                         [Ok] [Cancel] [Help]
   +-------------------------------------------------------------
```
where:
- Cleartool executable path - textfield - specifies the cleartool executable path
- Browse - button - opens a file browser