Keeping Track of Versions

DVID's Versioning

DVID might superficially seem similar to git with its hash-based UUIDs and a DAG. But since it typically stores large volume data and allows writing data to an "open" version (what would be considered the working directory in git), the version UUID is generated beforehand and not based on a hash of the committed data. Some key differences to typical revision-control systems you might already be familiar with:

• All writes and deletes are done on an "open" node (similar to git's working directory) so you can overwrite data that won't be versioned. This is necessary due to the potentially massive amounts of data stored and modified. Commits will checkpoint that version so at that point, the data is secure and always available via the version UUID.

• DVID branches require DVID commits: A "commit" in the DVID sense finalizes the work on a given node and locks it, disallowing further edits. Locking a node is a requirement to create new, unlocked branches under it.

• To continue with the current branch (which by default is "master"), use the /newversion endpoint to create a new child. To create an entirely new branch from a locked parent node, use the /branch endpoint.

• DVID allows you to set a UUID to provide some meaning to the identifier. This power should be done in moderation and for special versions like v1.0. We recommend locking a version that will be exported and then using branch and an explicit UUID (e.g., v1.0) that will then be locked. This allows you to make additional modifications off that "release" branch for v1.0 without disrupting the main branch.

Here are the pertinent endpoints for versioning and is part of what you'd see when asking for API help by calling http://my-dvid-server/api/help:

 POST /api/node/{uuid}/commit

	Commits (locks) the node/version with given UUID.  This is required before a version can 
	be branched or pushed to a remote server.  The post body should be JSON of the 
	following format: 

	{ 
		"note": "this is a description of what I did on this commit",
		"log": [ "provenance data...", "provenance data...", ...] 
	}

	The note is a human-readable commit message.  The log is a slice of strings that may
	be computer-readable.

	If successful, a valid JSON response will be sent with the following format:

	{ "committed": "3f01a8856" }

	A JSON message will be sent to any associated Kafka system with the following format:
	{ 
		"Action": "commit",
		"UUID": 
		"Note": ,
		"Log": [, , ...]
	}


 POST /api/node/{uuid}/branch

	Creates a new branch child node (version) of the node with given UUID.
	The branch name must be unique across the DAG.

	The post body should be in JSON format, where "note" and "uuid" are optional:

	{
		"branch": "unique name of new branch",
		"note": "this is what we'll be doing on this version",
		"uuid": 
	}

	A JSON response will be sent with the following format:

	{ "child": "3f01a8856" }

	The response includes the UUID of the new child node.

	A JSON message will be sent to any associated Kafka system with the following format:
	{ 
		"Action": "branch",
		"Parent": 
		"Child": ,
		"Branch": ,
		"Note": 
	}

	
 POST /api/node/{uuid}/newversion

	Creates a new child node (version) of the node with given
	UUID if no open node exists.

	An optional post body should be in JSON format:

	{ 
		"note": "this is what we'll be doing on this version",
		"uuid": 
	}

	A JSON response will be sent with the following format:

	{ "child": "3f01a8856" }

	The response includes the UUID of the new child node.

	A JSON message will be sent to any associated Kafka system with the following format:
	{ 
		"Action": "newinstance",
		"Parent": 
		"Child": ,
		"Note": 
	}


 POST /api/node/{uuid}/tag

	Tags a version with a unique string across the DAG (including UUIDs).

	The post body should be in JSON format, where the tag name is specified
	in the "tag" field and a "note" is optional:

	{
		"note": "this is what this tag means",
		"tag": "my-great-tag"
	}

	A JSON message will be sent to any associated Kafka system with the following format:
	{ 
		"Action": "tag",
		"Parent": 
		"Child": ,
		"Branch": "tag-",
		"Note": "Tag of version  with "
	}