Improve HISTORY in Designer: make more like modern version control systems

designer
(Arthur Shaw) #1

Here is questionnaire history in Designer:

image
image.png1201×249 23.2 KB

Helpful, but could be made more helpful by:

  • Showing what changed to what. Currently, history shows which objects changed, but not neither what about them changed nor what the previous and current sates of changed elements are. Basically, I’m looking for a rudimentary diff engine: tell me what changed, from what to what.
  • Showing (optionally) why the change was made. Currently, history tells me which object changed, but not why. To know this, one needs to keep scrupulous records outside of SuSo of what changed in SuSo and why. Basically, I’m looking for very basic (optional) commit messages.

To do this, a few proposed changes. The first set is, in my view, necessary. The second set is simply nice to have.

The necessary:

  • Allow the user to post an optional change description (aka commit message) upon pressing Save. This would allow users to describe both what they changed and why they changed it. If what they changed cannot be easily exposed/displayed in the UI, this change would be sufficient for getting the job done. This could be implemented in two complementary ways. In the UI, add an overflow menu to the Save button that, when clicked, displays the option “Save with comment”. In the keyboard shortcuts, add a shortcut that maps to this action (e.g., Shift+Ctrl+S)

The nice to have:

  • Expose in history the diffs between the each entry in history and the entry that immediately precedes it. Changes would be one of two types: additions or deletions. These changes would need to reference the property and the change (e.g., property: answer options, answer option: deleted “Yes”; added “Heck yes!”). Having anything, even if it’s somewhat hard to read, is better than nothing at all. This would lighten the load on user-written change messages: users would need only to describe why they changed something, not also what they changed.
  • Create a hash for each change and a link to that change entry. This would allow (advanced) users to link changes in SuSo to a repository of bug requests/changes in requirements (e.g., Trello board, ticketing system, etc.). That is, users could point via this link from a requested change to a change made.
  • Produce a compilation of changes since last import of questionnaire on HQ. Currently, users need to keep track manually of everything that’s changed between versions N and N+1 of a questionnaire deployed on the server. By producing automatically upon importing onto HQ (when the qnr had been previously imported), this serves two purposes. If the questionnaire is imported onto a testing server, this helps testing with manual unit and integration testing around changes. If the questionnaire is imported onto a deployment server, this provides helpful documentation of what changed and why. For HQ, this is internal documentation. For data collection in the field, this document could be manually “translated” to update field teams on noteworthy interviewer-facing changes.
1 Like
(Andrew) #2

Nice to have feature, but wouldn’t it be really annoying to write a comment on each save action? Maybe its better to provide some kind of explicitly created snapshots of the questionnaire? User manually saves state of the questionnaire with some comment and then is able to diff view between saved versions. Similar to how SVN works.

(Sergiy Radyakin) #3

I find it useful to tag specifically the versions (revisions) imported to some Headquarters.

For example,

2019-03-12 11:37 Imported to https://demo.mysurvey.solutions by user Sergiy

(Arthur Shaw) #4

Two quick answers to your great comments.

  • Prompts for comments could be annoying. I agree that it would be annoying to provide a comment for each save action. My ideas is that adding a comment would be optional. That way, a user could save without commenting–or being prompted to comment–while they are, say, building the questionnaire initially or making mundane changes (e.g., adding formatting to question text). But the user could add a comment by taking an additional action upon saving. That way, adding a comment is invisible to users that don’t want or need comments. My idea on making comments available but not annoying is to change the Save button’s appearance so that the user may click on an overflow menu associated with the Save button–for example, a v on the right hand part of a button that looks like [Save | v]–or use a keyboard shortcut to add a comment. Otherwise, saving would work as it does not: questionnaire gets saved without any prompts for comments.
  • Saving the state of the questionnaire so that saved states can be diffed. I like the idea, but worry (perhaps wrongly) that it would add an unwelcome layer of complexity for end users. What is not clear to me is how these saved states should be created, and which SuSo components doing the saving. Until a questionnaire is imported on a server, I think the user would indeed need to save states manually in Designer somehow. Once the questionnaire is imported on a server, I agree with Sergiy that it would be natural to save the state upon import. But only the user should should save the questionnaire state (as a version). Only the user knows at what point there is a version to deploy. Perhaps the Headquarters could prompt the user to save the state of the questionnaire upon import, but only the user should be able to save the state.