Test ended poker meetings after changed template

[mattkrick]

After a template has changed, we need to make sure that the old poker meeting is still accessible & works as a standalone artifact. Stuck on #4366

AC

• [ ] change the template after the meeting ended. change the dimension name, delete a dimension. delete a few scale values. change their colors. after each change, check out the ended meeting. it shouldn't bork.

Estimate: 4 hours

[jordanh]

Noting that #4366 has been merged, this is not blocked

[mattkrick]

it all works...but i still don't love it.

in a perfect world, the dimensions, scales & values for a meeting would persist even after that meeting ended. Changing the value 3 from red to blue should keep it as red for old meetings. changing the dimension name should not change it for previous meetings.

if we wanted to go down this path, there are some options for how we store the data:

• we just store gosh darn everything on the meeting (wasteful)
• every new meeting created a new dimension & scale object (wasteful)
• each dimension & scale object has an inactiveAt trait. changing the object just creates a new one & sets the inactiveAt for the old one. (wasteful because it's possible that no meeting is attached to these)
• when a meeting is started, we clone the docs, point to them & make them immutable. if an immutable version already exists, we just use that one. (a little wasteful, minimum 2 docs per template, no edits once meeting begins. bug or feature?)
• if above is a bug, then we do it at the end of meeting. we take the current template, dimensions, and scales & clone them & adjust the meeting.
• we create a whole new entity. a template is just a template. we create a, i dunno, Layout? Plan? Blueprint? ImmutableTemplate? so when a meeting starts, we look for an immutable template where mutableTemplateId === templateId. this will return an array. we got the most recent one. we then compare the name & scaleId. if they're the same, we use that immutable one. if not, we create a new one. then, we find a scale where mutableScaleId === dimension.scaleId. compare the hash of the name & values. if same, use them. if different, then create a new one & then create a new immutable dimension that points to the new scaleId.

i think that's the direction we have to go. rewritten for clarity:

• when a meeting starts, get the template. for each dimension in the template, get the scale.
• hash the scale values & scale name. look for an immutable scale by the hash. if not found, create it (scale values & name, doesn't matter if teams share this). update the immutable dimension with the sclaeId
• hash the dimension name & scaleId. look up an immutable dimension. if not found, make it.
• create or reuse a template that is the hash of the array of dimensionIds. attach the mutableTemplateId to it for analytics

[mattkrick]

stuck on team feedback

[jordanh]

I think taking some inspiration from git would be useful. This might be restating what you've suggested, in a different way:

• Templates are like "files" in github, you can mutate them whenever you want
• Meetings are like commits, when you run you "commit" and create a TemplateRef
  • If no changes were made to the template between meetings, you refer to the TemplateRef, else you make a new one

[tianrunhe]

Thinking out loud here: what if we put a version number to those entities (template, dimension, scale) and then a pair of (id, version) uniquely defines a set of entities used in a meeting. When an attribute changes in one of those versioned entities, we increment the version.

[tiffanyhan]

each dimension & scale object has an inactiveAt trait. changing the object just creates a new one & sets the inactiveAt for the old one. (wasteful because it's possible that no meeting is attached to these)

so no meeting is attached to some bc a new template is made each time an object is changed? what if we only create a new one if a meeting is started or ended, and the template is different from the one previously used? singling this suggestion out bc it seems the most intuitive to me

(this might also be restating what you were saying in a different way)

[mattkrick]

i love this thread so much. i think we're all saying the same thing in different ways!

• version bumping must occur on meeting start (or meeting end) because if we do it on entity change then we'll be creating versions that aren't ever used.
• we have to have a minimum of 2 versions (the one used for the meeting & the mutable one to be used in the future)

this stuff is probably pretty useful for retrospectives, but i figure poker meetings are new & more complicated so let's try it out there & see how it works.

Start vs. End

• doing this on end gives us the advantage of letting folks change the template mid-meeting. however, that means we have to support in-meeting changes. it also means that the meeting has to support a bivariant template (either a template or templateRef).
• doing this on start means a meeting can point to a single Instance, but if we do ever want to support in-meeting changes, we'll have to change the template as well as the TemplateRef for all currently active meetings.

[mattkrick]

stuck on postgres implementation. no sense in creating a new TemplateRef table in rethinkdb right now

[mattkrick]

• scaleValue = {color, label}
• scale = {scaleValues, name}
• dimension = {name, scale}
• template = {name, dimensions}

scaleValues and dimensions are difficult because those are arrays. pg can't do arrays of FKs, so we'd have to fully normalize & then add a sortOrder on the intermediary table. alternatively, we could just store those are arrays, but then we give up the relational good parts. alternatively, we could store them as JSON. or, we could store the whole thing as JSON in a single table.

the downside of saving it all a 1 big JSON is that analytics would be hard. it'd be hard to answer the question "how many meeting were run with 5 as a possible value". I mean we could, but someone else would have to write that query, because it'd hurt my head.

that said, it's probably best to guess reuse of each entity for user-defined templates:

• scaleValue will probably get re-used a LOT. With 12 colors & 100 numeric options, we've got 1200 possibilities (well, more including tshirt sizes, but i bet letters won't be that popular)
• scale likely has no reuse, except for the built-ins
• dimension is likely gonna be unique
• template will probably be unique

so, the sweet spot is probably down the middle. let's do an intermediary cache on scale & then reference that in the cached template. this way, we can easily figure out which templates are hot & which scales are hot.

AC

• [ ] A TemplateScaleRef table exists with an ID that is the hash of its scale json where scale = {name, scales[]}`
• [ ] A TemplateRef table exists with cols id, createdAt, name and dimensions. dimensions is a composite type array {name, scaleId}
• [ ] A TemplateDimensionRef (denormalized on TemplateRef) has a name, scale & sortOrder (gql only).
• [ ] a timestamp & hash is attached to each row so we can avoid dupe inserts & if the hashing goes wrong or bad things happen, we'll have a date to triage
• [ ] the JSON object is stringified using fast-json-stable-stringify
• [ ] the hash is a sha1 that is digested as a hex so it can be passed to pg easily as a btyea
• [ ] the graphql schema has a TemplateRef and TemplateScaleRef type
• [ ] a meeting has a templateRefId FK that is the sha1 hash.
• [ ] on meeting start, the hashes of the given template are taken & persisted to the DB (ON CONFLICT DO NOTHING)
• [ ] the template field in graphql meeting is deprecated
• [ ] the client uses templateRef instead of template in the meeting type

[mattkrick]

Migration checklist:

• jiradimensionfield replace dimensionId with dimension name. This is a big source of complexity because dimension refs don't have IDs since they're nothing more than a scaleRefId & name. so, we just the name as the ID. this means if a team creates a new dimension & uses the same name (e.g. "Story Points") then we'll link that new dimension to the same jira field as we did for the old dimension. This is actually kinda awesome.
• for every poker meeting, grab the template & persist it in the DB
• add templateRefId to every poker meeting
• delete the jiradimensionfields on the Team object. THey use dimensionId instead of dimensionName

Burndown:

• [x] VoteForPokerScoreMutation optimistic updater was broken, need to fix that or get rid of it.
• [x] Each EstimateStage has a dimensionRefIdx and removes a dimensionId
• [x] Jira Dimension Field adds dimensionName and removes dimensionId (or remove the entire thing if its too hard)
• [x] Every poker meeting now has a templateRefId field
• [x] all used templates & scales are added to pg
• [x] all access to templates, dimensions, and scales are audited to make sure we're not going off of them while in meeting