Managing review and bloat of omSupply reports

[fergie-nz]

The problem: New versions of omSupply reports are tricky to review!

Current dev pattern is to duplicate the entire file structure, bump version, and make changes.
When these changes are small, there is a lot of noise to cut through to see what has been changed.

Unix diff viewer can expose diff changes between to folders in the same repo.
Online tools are available to compare between folders eg
But these both add friction and reduce ease for reviewing team.

@jmbrunskill suggested that instead of duplicating file structure, we could instead:
Keep one version of the report
Bump the version and make changes when we want a new version
Append this to the standard reports json (so that the previous version remains).
If we did need to access the old version for whatever reason, this would need to be accessed via going to an old branch.

I wonder if anyone has any better ideas?

[CarlosNZ]

What about a little "bump version" script that copies the previous version from develop branch, duplicates the folder of the new version, and updates the version appropriately?

Then you can just do changes directly on the previous version and review them accordingly, then just run the script right at the end?

Do we currently have any protection against changes to the code, e.g. a checksum for each version that means the report won't run if it doesn't match? That would probably be a good idea to prevent accidental changing of versions (i.e. once a version has been "commited", it can't be changed -- we have something similar in place for template versioning in Conforma).

Probably needs a bit more thought, but I think it's probably worth getting right before getting too far down the road with report versioning. I'm happy to contribute to brainstorming if required.

[fergie-nz]

Currently there is no protection on previous versions of report other than PR / review process to not change the report, and rather create new one + bump version.

[andreievg]

If we are 'bumping' a report it would only be the patch, so can rename folder structure to just have major and minor.

The only reason to update major and minor if there is something 'new' that report relies on, in which case it's ok to copy with new major and minor

[fergie-nz]

That sounds good. I think we also need some kind of rigorous process or check otherwise reports will be updated without version bump.

It is very easy to do when fixing bugs etc, and then unclear about what version of a report a user might have:

[fergie-nz]

In case that image isn't clear, that is a fix of a report without a patch version change.