zugspitze / Hiking-Buddies

This repository is used to create bugs and new features for www.hiking-buddies.com
1 stars 0 forks source link

Route versioning #93

Open c-harding opened 2 weeks ago

c-harding commented 2 weeks ago

Currently, the creator of a route has the power to edit it, and the organiser of an event using the route does not. This works fine when the route was created specifically for an activity, and no other activities ever use the route again, or the route is never edited again.

Problems

However, it leads to problems in other cases:

  1. The organiser of an event cannot update the route to take into account temporary or permanent route obstructions, such as closed footpaths and changes to public transport.
  2. The creator of the route can make such changes specific to an event that they are planning on organising, and any other organisers are affected by these changes.
  3. Because it is not possible to switch the route attached to an activity, an organiser-creator who needs to replan an event may override their route, affecting any other activity that uses the original route.
  4. Participants receive a number of Hiking Buddies points proportional to the current difficulty of the route three days after the event finished, even if the route has been edited since the event took place.
  5. Because of the above problems (in particular № 1), it is often easier for an organiser to create their own route rather than reuse an existing one. This makes the routes map less usable (#6).

Proposal

Therefore I propose a versioning system for routes, as follows:

  1. Routes are versioned. When a route is edited, the new version is saved as a copy, with the same route ID but a new version ID.
  2. If only the description/title/other metadata is edited, no new version is created. However, the metadata is saved with a version, so changes to metadata do not affect the metadata of previous versions.
  3. Events reference a specific version of a route.
  4. Unreferenced old versions do not need to be kept. This means that only the newest version and the version(s) tied to events are kept.
  5. When a route is updated, organisers of upcoming events using this route are given the choice to switch to the latest version.
  6. When given the choice to upgrade to the latest version, a diff is shown. This includes a text diff of the description etc (if changed), and the two routes on the same map, with the two elevation profiles above one another.
  7. An organiser can edit the route of an event at any time, including the metadata. This does not affect the original route. If the organiser is also the creator, they have the option to edit the route of an event without editing the original route, or to edit both simultaneously.
  8. A route creator can choose to adopt an organiser’s version of the route as the main version. This creates a new version, identical to the organiser’s version.
  9. An organiser can request that an organiser adopts their version. This is handled as a native notification, either in the UI or by email, and the notification provides a link to the diff and a button to adopt the changes. At this point, the creator can also choose to transfer the route to the organiser, so they are now seen as the creator. This is useful if the route creator no longer lives near the route, and no longer feels able to maintain the route.
  10. A second organiser can create an event based on an event’s version of the route, rather than the main version of a route. This will yield a warning if the event’s version is older than the main version of a route.
  11. Events can be cancelled without deleting them from the website. This allows for organisers to reuse cancelled events’ versions, and even reuse their description as a starting point.
  12. If a user deletes their account or is inactive for a long period of time, it is unclear how to handle route edits from organisers. Maybe moderator users can review the edits and choose to transfer the route to the organiser? (#67)

Implementation

Proposal 4 massively reduces the storage demand compared to Proposal 1 itself. We need to store the latest version of a route, and each version tied to an event. Ideally, we do not duplicate entries in the database if the route has not been changed between the event and the route.

Database migration

Instead of a single database table representing a route, now we need two: let’s call them route and route_version.

Each event also needs a route version, set to zero for existing events.

The route version can either be a timestamp or a serial number assigned by the database. Pure incrementation does not work, because different events can create an edit from the same version of a route.

Operations

When a route itself is edited by its creator, the route_version entry is copied with a new version number. The route table is updated to reference the new timestamp. If the previous version is not referenced, it can be deleted. (If the route is not referenced from any event, the route can also be edited inline) If the previous version is referenced by other events, the event owners are sent a notification that there is a new version available.

When the route of an activity is edited by the organiser, the route_version entry is copied with a new version number. The route table is not updated. The event table is updated to reference the new version. If the previous version is not referenced, it can be deleted. (If the route is not referenced from any other event or the route table, the route can also be edited inline)

When an organiser updates their event’s route to the newest version, only the event table’s version number is changed, and the old version’s route is deleted if it is not referenced.

When a route creator adopts an event’s version of a route, the route version number is updated. The old version of the route is deleted if it is not referenced.

Race conditions

Every operation to delete a route version runs the risk of race conditions. Make sure that any checks to determine whether existing versions are used are performed in the same transaction as the update/deletion. Make sure any UI operations to create events/update versions include the expected version number, and prompt the user to check the latest version of the route if the version number has changed.

Possible extensions

  1. Organisers could update their event’s version of a route based on another event’s version of a route, rather than based on the latest version of the route.
  2. Users’ “favourited” versions of routes could also be versioned. In this case, the favourited version table in the database would have to be checked too before deleting any entries in the database.