Created Design: Version Control (markdown)

2016-07-12 15:42:37 +01:00 · 2016-07-12 15:42:37 +01:00 · 9e918210b5
parent 34de7cded6
commit 9e918210b5
1 changed files with 88 additions and 0 deletions
--- a/Design:-Version-Control.md
+++ b/Design:-Version-Control.md
@ -0,0 +1,88 @@
+When we talk about version control of node-red instances, there are two things that it covers:
+
+1. the nodes added to the environment via npm
+2. the deployed flows (+credentials)
+
+It is desirable to have a single artefact (or logical set of artefacts) that can be maintained in version control and used to restore a system to a previous known state.
+
+### Added Nodes
+
+Currently, a user simply npm installs nodes in their user directory to add them to the runtime - or uses the admin api to do so. There is no requirement to maintain a `package.json` file. But it is that file that needs to be version controlled in order to have a restorable system.
+
+This raises some questions:
+
+ - should we try to create/maintain a package.json file under the user directory - in much the same way that `npm install --save` does.
+ - should we do this via the Storage API so alternative (non-filesystem) based solutions can make use of it
+
+### Deployed Flows
+
+Use cases include:
+
+- a user creates a new version of the flows by simply clicking deploy
+
+```
+  [v1]
+    ^
+Deploy new version:
+  [v1]-----[v2]
+             ^
+```
+ - a user can _optionally_ add a comment to the version
+
+```
+     [v1]-----[v2:My New Flows]
+                ^
+```
+ - a user can see a history of versions - showing date/time + comment (aka `git log`)
+
+```
+     [v1]-----[v2]-----[v3]-----[v4]
+                                 ^
+```
+ - a user can revert to a previous version (aka, `git checkout <commit>`)
+
+```
+     [v1]-----[v2]-----[v3]-----[v4]
+                                 ^
+Revert to v2
+     [v1]-----[v2]-----[v3]-----[v4]
+               ^
+```
+ - having reverted, a user can restore a future version (aka, `git checkout <commit>`)
+
+```
+     [v1]-----[v2]-----[v3]-----[v4]
+               ^
+Revert to v4
+     [v1]-----[v2]-----[v3]-----[v4]
+                                 ^
+```
+
+ - having reverted, by clicking deploy, the user can either chose to either erase the future versions, or add the new version at the end of the 'chain':
+
+```
+     [v1]-----[v2]-----[v3]-----[v4]
+               ^
+Erase future:
+     [v1]-----[v2]
+                \------[v5]
+                        ^
+Append:
+     [v1]-----[v2]-----[v3]-----[v4]-----[v5]
+                                          ^
+```
+
+
+## API
+
+Whilst clearly influenced by git as a likely common backend, the version control API needs to be careful to abstract the operations it provides sufficiently so that alternative VC systems can be used underneath it. It does not require the full breadth of capability that git provides (branching/merging etc).
+
+
+The basic operations are:
+
+ - save a new version of flows/credentials with an optional description. This returns a version id.
+ - get the latest version - defaults to the most recent version, but a version id can also be specified
+ - get the version history - returns a list of id/timestamp/describtions
+ - revert to a given version
+
+