Versioning Action Execution Pattern

This paper discuss versioning actions processing. I suspect that it can form a Versioning Action pattern.

Clients

UI

enablement logic, user options, results presentation (output log and file annotations)

Versioning system

limited recursivity, file categorization (e.g. binary vs text files), workdir preparation

IDE integration

shareability query (internal ignore list), background operation vs. editor.

User Action Sequence

Actions that are explicitely requested by user follows:

1. Check action enablement. Possible criteria: location in versioned directory, file flag, folder flag, root flag, existence flag, online mode flag, already running concurrent operations, locking and locker status or versioning status, natural recursivity (folder remove) on non-recursive logical views (package). If some criteria is missing such as not yet known status (e.g caused by background operation failure) only action that fixes this should be allowed (i.e. no silent pre-commands).
2. Check basic preconditions. Check network connection if in offline mode possibly suggesting switching to online mode. Check basic authorization if it's possible (otherwise see error detection). Save all modified entities (files in traditional VCS systems).
3. Ask user for additional options. Typically showing a dialog. It sometimes results in enablement logic reevaluation. It depends on versioning system but e.g. selecting shalow/flat operation can theoreticaly lead to finding that that are no files that are subject of the operation. Also user may fail to provide required data such as commit message, selects invalid target directory, etc.
4. Setup actual versioning system operations. If invoked in local directory assure that whole parent directory structure is added. If versioning system does not support recursive operations required by user prepare list of versioning operations. If versioning operation requires per file flags split it to list of operations. Yet another possible operations split based on consulting IDE integration about ignoring files (listed in SharabilityQuery). Depending on versiting system splitted operations should flagged to be done in atomic transaction.
5. Execution phase. If done at background then depending on operation mode (read-only or read-write) avoid concurrent file usage be editor. For foreground operations allow to send then to background (explicit request that can close editors etc.).
6. Operation result visualization. Action presents one result regardless of how many operations it was splitted to. Provide a progress feedback and operation cancellation whenever possible.
   Error handling. Operations can fail for various reasons. Always pass as many diagnostics messages as possible. Two special cases should be detected: broken network connection and missing permissions (e.g. login). In such case corrective actions: setting offline mode or login are suggested then reexeute (it can stop at enablement step) the sequence skiping gathering user data.
7. Programatically interpret operation output and update internal structures (here status cache). For operations without feedback execute post operations that allows to update required structures.
8. All spawned threads finished? We are done. Update result visualization possibly providing addition operations such as: go to checked out folder, or checkout just tagged branch, or rebuild updated project.

Background Action Sequence

Should such operations exist they follow above sequence but must not require any user input nor show any user focus taking feedback.

Special care must be taken about concurrent modifications coming from editor and for error reporting. The right solution is that operation sets a error flag that is then interpreted by enabling only explicit user action that corrects it. Also background operation must not block enablement of user actions. It must be suspended.

Tear Off

The article needs review and patch from Martin that knows and probably discovers at least one corner case.

---

Petr Kuzel on Feb 4 2005