Version Management Proposal

[farisd16]

Feature Proposal

Spec Version 0.2.0

Context

Problem

Currently, users can’t track changes made to diagrams and feedback is not linked to a specific version, which makes it more difficult to collaborate and engage in a feedback loop. There is no way to revert to previous versions or restore them.

Motivation

Considering that UML modeling is a collaborative activity and plays an important role in the software evolution of model-driven development, version management of diagrams is crucial for projects that utilize Apollon for creating and maintaining UML models.

Requirements Engineering

Existing (Problematic) Solution / System

If a developer wants to create another version of the diagram, the only way would be to import the diagram into a new file. In order to see an older version, it has to be stored and imported into the editor.

Proposed System

In the standalone version of Apollon, users will be able to toggle the visibility of a sidebar which displays a list of versions of a diagram. The user can see a preview of each version, delete, restore or edit them. Each version in the list has its title and description. The sidebar will also have a “Publish Version” button so that the user can create a new version of the diagram given the current state of the diagram.

Requirements

Functional requirements:

• FR1: Add new versions: Developers will be able to create new versions of a diagram
• FR2: See list of versions: Developers will be able to see a list of versions of a diagram
• FR3: Preview version: Developers will be able to view each version of a diagram
• FR4: Edit version info: Developers will be able to edit version info of a diagram (title and description)
• FR5: Restore version: Developers will be able to restore a version of a diagram

Nonfunctional requirements:

• NFR1: Reliability: Saved versions will persist
• NFR2: Availability: Versions can be previewed and modified at all times
• NFR3: Usability: Users will have an intuitive sidebar for version management

Analysis

Analysis Object Model

System Architecture

Subsystem Decomposition

I intend to add a new POST endpoint /diagrams/:token/publish. The request body will contain the new diagram to replace the existing one saved under a token.

Currently, diagrams are stored as:

id: string;
title: string;
model: UMLModel;
lastUpdate: Moment;

In order to support the described functional requirements, I have two options:

• Add a prevVersionId and description field. Upon loading a diagram into the editor, the version history would be deduced by traversing trough the "linked list" of a diagram.
• Change the model: UMLModel field to models: UMLModel[]. The chronological order of versions would be deduced from indexes in a ascending manner. I would also add title , description and lastUpdated fields to the UMLModel Apollon datatype, to enable FR2 and FR4. The models array stored on the server will not contain the last element from the models array in local storage, as it represents the "Current Unpublished Version". However, I am unsure about how I would handle this migration. Would I have to make sure that both formats are supported at once? The UMLModel datatype comes from the Apollon NPM package.

Other Design Decisions

Currently, when clicking any button in the share modal (Edit, Give/See Feedback, Collaborate, Embed), a new token is generated. For version management, this means that if someone embedded a diagram, as described in #92, and then shares it to get feedback for example, the embedding would become stale. My solution idea is, if a diagram had previously been shared, and the user clicks on a button in the share modal, then another modal pops up. This modal would explain that the user can either discontinue the version history of the previously shared diagram or not, and let the user choose.

Discussion Points

• Which of the mentioned approaches to changing the diagram datatype is better? Is there a better approach?
• Should version actions be icons as shown on the screenshots, or part of a dropdown menu?

UI/UX Design

First draft of the sidebar is already implemented on the branch linked to the issue.

[FelixTJDietrich]

Generally looks good already.

Here are some questions / remarks that I have in mind:

• Does UMLModel contain a timestamp?
• Does this change require a migration? We have to keep apollon-ios in mind, is there a way to not make it a breaking change? Maybe by having a prevVersionId or so
• What happens to feedback? I think the flow would be: work on diagram v1 -> publish version & share with others to get feedback -> receive feedback on v1 -> implement feedback in v2 -> publish version -> ...
  • This feedback loop is IMO a core part of even having a version history
  • I'd guess the feedback for a version is only visible for the currently viewed version (this deviates from Figma since there you always see all feedback regardless of the version)
  • A feedback indicator in the version history would be nice (this deviates a bit from Figma)
• Are you doing autosave versions? Or is it always triggered by a user?
• I think a duplicate action like in Figma would be good so you can "fork" that version
• The actions do not have to be buttons IMO, you can do it like Figma with the "..." and have a dropdown selection
• How will this work in the context of collaboration?

Please highlight the open discussion points that are important to talk about with Stephan and me where decisions are necessary, such as migrations. On those points you can also offer multiple alternatives that you have considered.

[farisd16]

Does UMLModel contain a timestamp? Does this change require a migration? We have to keep apollon-ios in mind, is there a way to not make it a breaking change? Maybe by having a prevVersionId or so.

• That's a good idea, with the prevVersionId I can avoid breaking changes. Also, UMLModel doesn't contain a timestamp, but it wouldn't be needed with your approach since the Diagram has the lastUpdated field.

What happens to feedback? I think the flow would be: work on diagram v1 -> publish version & share with others to get feedback -> receive feedback on v1 -> implement feedback in v2 -> publish version -> ...

• Feedback (assessment) is part of the UMLModel datatype, and will therefore be linked to a single version. This means that the flow would be just as you have specified. However, the feedback system of Apollon is currently specifically designed for instructors to grade diagrams. As Eugene pointed out in his evaluation here, standalone Apollon lacks commenting for free-form discussions. Such discussions can be carried out in a PR/issue, and perhaps commenting as part of standalone Apollon is a feature that could be implemented in the future.

Are you doing autosave versions? Or is it always triggered by a user?

• The "Currently Unpublished Version" is the autosaved version that hasn't been published yet, whereas published versions were created by clicking on the + button, like on Figma.

I think a duplicate action like in Figma would be good so you can "fork" that version

• There is currently a "Restore Version" button that is available once a preview of the diagram is opened. That is what you mean by "forking", right?

The actions do not have to be buttons IMO, you can do it like Figma with the "..." and have a dropdown selection

• I thought it would look better this way. If you think it is better with a dropdown I can implement it that way too.

How will this work in the context of collaboration?

• If you are referring to collaboration from the Share modal, my idea is that version management is also available within collaboration mode and that all collaborators have access to it.

[FelixTJDietrich]

There is currently a "Restore Version" button that is available once a preview of the diagram is opened. That is what you mean by "forking", right?

I meant this pencil button that looks like an edit button. I think if you'd click that one it would create a duplicate of the diagram for editing. I think restore version would be a separate functionality that we also want.