The big question: How should we handle template versioning so that we can manage migration?
Notes from the Slack conversation with Sri and Ben:
versioning in templates to detect when new features or formats have changed, but what format?
how to coordinate version changes in templates to a specific commit, tag, or feature delivery?
what are the events that would trigger a version change?
can a "build serial number" be created through some mechanism automatically, so when it's documentation we just use that as the reference?
can the changelog itself be the data structure that serves as one of the references?
can we use more than one reference number?
how to handle outside assets that do not get versioned? Like art-assets in GEMSTEP?
Use cases
Actions that are related to template versions.
The template format might change if we need...
new project parameters (e.g. add mandatory duplicateWarning text)
new feature parameters (e.g. add filter function and parameters like filterFadeHelp)
new built-in fields (e.g. updatedBy)
new schema parameters (e.g. 'isProvenance' added to field definitions so they appear in the Provenance tab)
adding new parameters only under certain conditions (e.g. only adding provenance if the current template schema calls for it, skipping it otherwise).
Loading an existing project (and associated project template) needs to...
gracefully migrate existing fields so that the data can load without crashing
migrating fields from one format to another if it's warranted
...but sometimes you definitely do NOT want to migrate the field because you want to keep the data as-is, instead just supporting being able to load and view the data without breaking
record template versions so that we can associate a required change with a version
templates without a version are assumed to be somewhere between 1.0 and 1.x. Currently I believe the app can successfully migrate any template up to 2.0.
Manually updating an existing project template in order to...
bump the version number to enable new features (e.g. introducing version control; e.g. validating templates only for specific versions of the template schema)
manually add new fields/parameters to convert or take advantage of new features.
Creating a new default template from the current template-schema.js definition.
Changes to the template schema requires generating a new default template to be used with new projects.
The new default template should be mapped to a specific version id (whatever that might be).
Viewing a historical graph
Sometimes you might want to view an old project graph using the version of the tool that was being used to create the graph. In this case, you need to know which Release of the app to use to open the project.
This is particularly an issue for researchers who might need to revisit the graph from an old study. Theoretically the modification date of the project should provide some clue to the associated release, but this is not reliable.
General questions:
Should templates ALWAYS gracefully migrate no matter how old they are? Or is there an upper limit? e.g. only migrate after version 1.5? (I believe we can load any version after 1.0, but I haven't verified that).
When should CHANGELOGs be updated? With every PR? Should CHANGELOGs be a frequently updated developer-facing log, or an infrequently updated user-facing log tied to periodic releases?
RELEASES should be infrequent and user-facing, typically tied to a particular pilot, study, or other pivotal event. The key information should help users understand the high level user-facing changes in the tool, and in particular, mark changes in template or project format and key technical changes.
CHANGELOGs should be added to each PR, so we have a list of all changes? These are developer-facing and can and should include low-level technical updates.
Possible Solution: Use github Release Versions
Ben's first proposal was to use github Release versions. This is the current implementation as of dev-bl/provenance around May 24th, 299721e025b3280861cf0a2b9775aafa24ba2bad.
PROS:
It's easy to map a project template, default template, and the template schema to the current release. e.g. you can look at a template file and know which release of the app you should use to view the historical graph.
CONS:
Have to manually update the template schema whenever the format changes.
Interim versions are hard to track -- e.g. if developing a feature takes two weeks, all of the interim versions are glossed over, which might actually be appropriate.
Not always visible to the whole dev team.
Need proper semver protocols
Need to use a semver utility to handle math
Possible Solution: Use build numbers
Sri's proposal is to use build numbers that are automatically generated with each compilation.
PROS:
build numbers can be automatically generated and stored in a file, e.g. build-versions-*.json.
no need for manually updating versions
allows for interim versions
does not need nor rely on semver
CONS:
during a sprint, the build number may need to be constantly revised. Likewise the corresponding template-schema.js, default.template.toml, and <project>.toml will have to be updated? Or we need to initially use an arbitrary build early in the sprint, but before the PR, "burn" the build number into the final push? Or just use an early build with the understanding that the template changes come some arbitrary number of builds after the PR so we don't need to remember to manually "burn" it in.
it's less clear which Release should be used to load a project unless the CHANGELOG contains a solid reference to the build number (is this then yet another manual update situation?)
how hard/easy would it be to find the build number associated with a commit? If the version is baked into build-version-*.json can it be searched quickly?
If two developers are working on different branches, could they end up with matching build numbers?
Criteria / Principles
Minimize manual updates, automate as much as possible.
Some kind of human readability of the version in template-schema.js, _default.template.toml, and <project>.toml as well as Release notes or CHANGELOG notes.
Whole team visibility, including outside developers
Loading newly created or old existing projects or templates should not break the app -- fail gracefully.
The big question: How should we handle template versioning so that we can manage migration?
Notes from the Slack conversation with Sri and Ben:
Use cases
Actions that are related to template versions.
The template format might change if we need...
duplicateWarningtext)filterFadeHelp)updatedBy)provenanceif the current template schema calls for it, skipping it otherwise).Loading an existing project (and associated project template) needs to...
Manually updating an existing project template in order to...
Creating a new default template from the current
template-schema.jsdefinition.Viewing a historical graph
General questions:
Possible Solution: Use github Release Versions
Ben's first proposal was to use github Release versions. This is the current implementation as of
dev-bl/provenancearound May 24th, 299721e025b3280861cf0a2b9775aafa24ba2bad.PROS:
CONS:
Possible Solution: Use build numbers
Sri's proposal is to use build numbers that are automatically generated with each compilation.
PROS:
build-versions-*.json.CONS:
template-schema.js,default.template.toml, and<project>.tomlwill have to be updated? Or we need to initially use an arbitrary build early in the sprint, but before the PR, "burn" the build number into the final push? Or just use an early build with the understanding that the template changes come some arbitrary number of builds after the PR so we don't need to remember to manually "burn" it in.build-version-*.jsoncan it be searched quickly?Criteria / Principles
template-schema.js,_default.template.toml, and<project>.tomlas well as Release notes or CHANGELOG notes.