Goal
The goal of object revisions management feature is to allow to keep a state of object and its attributes in history, allow to check differences between different states, allow to restore specific historical state.
Definitions
HP - History Point – an unique (within the Project) ID for each arKItect operation. Any operations with object revisions has own HP. HP can be used as reference for any operation.
object revision - a stored state of object. The revision details includes object name and set of values of all object attributes (without respect to active filter). Revision description includes : HP (moment of revision creations), name (revision name), comment, creation time and acting user.
restore revision - use can decide to restore object to some older revision. This means, that object will be restored to the state stored with revision. Object name and values of all his attributes (without respect to active filter) will be restored with revision details.
GUI
The revision management GUI is accessible with right-mouse-click menu on objects (both from graphical views and treeviews) or directly from object properties (there it is also possible to see last revision and its state)
access object revisions from graphical view |
access object revisions from treeview |
access object revisions from properties |
|---|
Create Revision
User allowed to create a new revision only if there any changes for selected object since last 'create revision' or 'restore revision' action.
Using Create Revision dialog user can set a revision number and an optional comment. Revision number is auto-incremented by default, to edit revision number, please, uncheck "Set revision number manually".
"Current Revision" displays the object's last revision number followed by asterix (it signifies that there are changes comparing to the last revision) and global project revision number in parenthesis.
If user tries to assign an existing revision number, arKItect will warn user about it proposing either to replace the old revision with the new one or abandon action.
arKItect will inform user whether revision was successfully created or not.
Show revisions
Existing object`s revisions are shown with the 'object revisions' dialog. With this dialog user can look on revision properties, compare revisions (two revisions or one revision and current object state), restore older revisions or see object's changes history.
Here is a detailed description of all possible actions. To call an action user should select one (or also two for 'Compare') revisions and press the desired button.
Properties
With this dialog user can see the object name and all values of object`s attributes stored in thу selected revision without respect to active filter
Compare
It is possible to compare object states with the 'Compare' button. To compare two different revisions user can select two lines in 'object revisions' dialog. To compare some revision and the current object state - select only one revision. The 'Comparing' dialog shows revisions information and values of object attributes (with respect to active filter). Toggle 'Show differences only' to show all attributes or only the ones where changes are observed.
Restore
To restore the current object state to desired revision state, user should select the revision and press 'Restore' button. Object name and all its attribute values will be restored to the state stored with the revision. Object name will be restored with 'duplicated names' check applied and indexed if object with same name already exists.
arKItect will inform user whether restore operation is done successfully or not.
History
'Create revision' and 'Restore revision' actions are reported in history, and can be seen in object`s or general history. Value field for 'restore revision' operation describes the HP of 'revision where we restored to'.
CM
Collision management feature is applied for create/restore revision operations on the object level. E.g. if two users tries to create a revision for one object at the same time, the 'second user' will be informed about the 'first user' activity
Revisions for multiple objects
All objects
It is possible to see and manage revisions of all objects in the project. To do so click Object under Revisions in the Configuration Management Category.
Selected objects and its children
It is possible to see and manage revisions of some hierarchy of objects. To do so use right-mouse-click menu on objects (both from graphical views and treeviews)
access object revisions from graphical view |
access object revisions from treeview |
|---|
Objects Under Revisions Dialog
The following dialog will be displayed:
Here, all objects under revision control are shown. "Current revision" column displays last revision number for each object (along with asterix if changes are present) and object's global history number. "Create revision" column displays a check-box (checked by default, it means "Create revision" will be applied for the object) for all objects for which a new revision can be created. "New revision" column displays the revision number that will be assigned to the newly created revision.
Objects can be filtered by name
Or by type
Or by name and type
Checking "Show all objects" check box will make appear all objects in the dialog - those under revisions control and those not under revisions control yet.
Setting this check is useful when there are no revisions yet and user wants to initialize objects with the first revision. 'n/d' stays for "not defined" (revision). All objects without revisions yet are assigned with version "1.0" by default.
"Revisions..." and "History..." buttons allow to access list of object's revisions and object's history of modifications correspondingly.
Using this interface it is possible to create new revisions. By checking/unchecking a check-box for different objects in "Create revision" column, user can set the list of objects he would like to create new revisions for:
unchecking "Create revision" option for single object |
unchecking "Create revision" option for multiple objects |
|---|
When checking/unchecking a check-box "Create revision" for multiple objects, it is important to hold Shift/Ctrl key when doing selection and checking/unchecking the check-box. As soon as the check is set/unset in the cell it will propagate the value to all selected objects. The same works also if you make selection with a keyboard (pressing white space for checking/unchecking - to do so, a cell with a check-box needs to be activated).
By changing revision numbers in "New revision" column user can adjust revision numbers proposed automatically:
Now, when all desired objects are filtered, check-boxes are set properly and new revision numbers are defined, user may press "Apply" button to create revisions for affected objects. After revisions are created, the list above is updated:
Here, all objects (for which check-boxes were checked) are now displayed with new "Current revision" (set in accordance with "New revision" of the previous picture), while the last object wasn't updated as it was not checked in "Create revision" column. User can still press "Apply" now to create new revision for the last available object.
Logic
Technically, object revisions data are stored on the server side in tables very similar to general storage tables. At the create/restore revision actions the data is simply copied from one table to another.
Additionally, at the Create Revision moment the server stores actual attribute values - it makes sense when several users works on same project simultaneously.
In the case of metamodel changes (deleting types/attributes) revision data is cleared.