Guided Tour Updates Workflow

Purpose: Establish a structured process for managing guided tour updates across the PermaplanT initiative.
It ensures that all changes affecting the guided tour are consistently reviewed, implemented, and documented, reducing ad-hoc handling and maintaining a coherent user onboarding experience.

Audience: Contributors who work on features relevant to guided tours, guided tour owner, product owner
Status: Draft

Rationale

A consistent system is needed to track which changes to the application impact the guided tour.
Without such a system, maintaining an up-to-date and coherent guided tour becomes difficult.
The aim of this workflow is to establish that system and ensure guided tour updates are managed reliably going forward.
This covers:

  • The mechanism for collecting changes that impact the guided tour
  • The roles and responsibilities of the involved parties
  • The prioritization process for guided tour updates
  • The integration of these activities into existing workflows

Workflow Steps

1. Identify and Tag Changes Affecting the Guided Tour

1.1 Issue Author Identifies Guided Tour Impact

Who: Issue author
When: When creating the issue

Actions:

  • If the issue is expected to affect the guided tour:
    • Add the affects_guided-tour label to the issue (if not already present).
    • Optionally describe how the issue may impact the guided tour.

Result:
Guided tour relevance is documented early and can be considered during implementation.

1.2 Triager Identifies Guided Tour Impact

Who: Issue triager
When: During issue triage or refinement

Actions:

  • If guided tour relevance is identified during triage:
    • Add the affects_guided-tour label to the issue (if not already present).
    • Optionally add a short clarification note.

Result:
Guided tour relevance is captured even if it was missed at issue creation.

1.3 Issue Implementer Identifies Guided Tour Impact

Who: Developer implementing the issue
When: During or after implementation

Actions:

  • If the merge request implements an issue that is already tagged with affects_guided-tour, or if it becomes apparent during implementation that the change affects the guided tour:
    • Ensure the guided-tour checkbox in the MR template is checked.
    • Add the affects_guided-tour label to the merge request (if not already present).
    • Document in the changelog (dev.md) under Changes Affecting Guided Tour how the guided tour is affected by this MR.

Note: In case you are unsure if the merge request affects the guided tour it's best to tag it with affects_guided-tour to be reviewed by the tour owner.

Result:
Guided tour impact is consistently consolidated at the merge request level and properly documented, regardless of when it was identified.

2. Tour Owner Reviews Merge Requests

Who: Tour Owner
When: On releases, when reviewing changes relevant for guided tour updates

Actions:

  • Review merge requests that:
    • are tagged with affects_guided-tour, and
    • are either:
      • tagged with MR::please_review, or
      • already merged
  • Review the changelog entries (dev.md) describing how the guided tour is affected.
  • Select merge requests based on priority:

    1. Read the documentation (especially the changelog entries in dev.md) explaining how the change impacts the guided tour.

    2. Based on this information, prioritize merge requests including:

      • Merge requests with user-facing changes
      • Merge requests that introduce features with low discoverability
      • Choose groups of related merge requests if sensible

    3. Create an issue documenting the selected merge requests and planned guided tour changes.

    4. Request review from the product owner and await approval to ensure quality of tour updates.

Result:
Merge request(s) selected for guided tour updates.

3. Update Tour According to Chosen Merge Request(s)

Who: Tour Owner
When: After selecting merge request(s)

Actions:

  • Implement the needed changes to the guided tour based on the selected merge request(s).
  • Changes to the tour can be done in one MR if the addressed changes are related or separate MRs for independent changes.
  • Remove affects_guided-tour label from the covered the merge requests.

Result:
Selected merge request changes are reflected in the guided tour.

Special Cases

Unclear Guided Tour Impact

If the impact of a merge request on the guided tour is unclear:

  1. Contact the merge request author by:
    • leaving a comment on the merge request asking for clarification.

Examples

Example 1: Standard Guided Tour Update

Step 1: Issue or MR is tagged with affects_guided-tour.
Step 2: Developer documents guided tour impact in dev.md.
Step 3: MR is marked MR::please_review or merged.
Step 4: Tour owner filters MRs by affects_guided-tour.
Step 5: Tour owner reviews changelog entries and MR content.
Step 6: Tour owner determines merge request(s) with highest priority.
Step 7: Tour owner presents selection to Product Owner in a separate issue.
Step 8: Selection is approved.
Step 9: Tour owner implements guided tour changes.
Result: Changes introduced by the MR are covered in the guided tour.

Example 2: MR Selection Not Approved

Step 1: MR is tagged with affects_guided-tour.
Step 2: Guided tour impact is documented in dev.md.
Step 3: Tour owner selects MR(s) for guided tour update.
Step 4: Selection is presented to Product Owner.
Step 5: Selection is not approved.
Step 6: Selection is adjusted according to feedback.
Step 7: Tour owner implements guided tour changes.
Result: Guided tour is updated according to the approved selection.
  • Decision on how issues affecting guided tour are collected (../decisions/frontend_collect_guided_tour_changes.md)
  • Labels documentation

Troubleshooting

Common Issues