Roadmap Management

Overview

The roadmap is the set of features and improvements we plan to deliver. Every roadmap item is tracked as a GitLab Epic and mirrored publicly on the website at selorahomes.com/docs/roadmap/ .

The key rule: the Epic description is never edited directly. It is a mirror of a file in the website repository, and all content changes go through a reviewed Merge Request. This keeps every change visible, reviewed, and traceable.

Epics

Roadmap items are managed with GitLab Epics in the selorahomes/products group, so we can create work items underneath them for the team to track work.

To add a new roadmap item, start by creating a placeholder Epic in the group. Keep the description minimal at this point: just the permanent header below. The real content is filled in later, through a Merge Request (see Managing Epic content ).

Permanent header

Every roadmap Epic description must always begin with this header. It is identical on every roadmap Epic, and stays at the top even after the content is synced:

> **Warning:** This Epic's description is managed as documentation and mirrors a file in the
> website repository. Do not edit it directly. See [how we manage the roadmap](https://selorahomes.com/handbook/departments/product/roadmap-management/)
> and propose all content changes via a Merge Request.

Labels

Apply the correct labels when creating the Epic.

Workflow

The workflow:: label tracks the state of a roadmap item. New Epics start at workflow::draft and move forward through the pipeline:

workflow::draft → workflow::backlog → workflow::planned → workflow::in-progress → workflow::in-review → workflow::done

The website reads this label to display the roadmap item’s status badge, so it always reflects the current state of the Epic.

Managing Epic content

Epic content is not managed by editing the description directly. Editing in place produces changes that are never reviewed and go unnoticed.

Instead, we update the website, which reflects the state of our roadmap at selorahomes.com/docs/roadmap/ . All content changes are made via a Merge Request in the selorahomes.com repository, under content/docs/roadmap .

Once a roadmap Merge Request is accepted and merged, the Epic description is synced with the content of the file, without its front matter. The permanent header is kept at the top of the Epic description.

The sync flow, in short:

1. Open a Merge Request in the website repo editing the relevant file in content/docs/roadmap/.
2. Get it reviewed and merged.
3. The Epic description is updated from the merged file (front matter stripped), keeping the permanent header at the top.

Feature SSOT

Roadmap item statuses must stay in sync with the feature single source of truth, data/features.yaml , in the website repository. When you change the status of a roadmap item (its workflow:: label), check that the corresponding entry in features.yaml reflects the same state (for example, a feature’s status: roadmap versus status: available).

See Feature SSOT for how we maintain features.yaml and the rest of the data/ directory.