🗺️ Roadmap App — User Manual

1. Overview

The Roadmap app displays project milestones on a Gantt-like timeline. It shows milestones from two source types:

• Epics (issue type "Epic") — only when the Epic has a due date (duedate).
• Releases (Versions) — when versions exist and have release dates.

Milestones are shown per project according to the current saved view or the default (no view). Saved views control:

• Which projects appear on top (project order).
• Which projects use Epics vs. Releases (milestone selection).
• Project colors and availability metadata.

Saved views can be either Everyone (visible to all users) or Only me (visible only to the current user).

2. Quick Start

1. Open the app

   Launch the Roadmap app. The timeline shows milestones for projects with active milestone selections.

2. Open Configuration

   Click the gears icon (⚙) to open the Configuration modal.

3. Configure your projects

   In the modal you can: reorder projects (▲ / ▼), change project colors (click the color swatch), and enable Use Epics or Use Releases for any project.

4. Save a view

   Click Save new view to persist your configuration. Load saved views from the dropdown — each shows an owner badge (Everyone / Only me).

3. Data Requirements

Milestones will only appear when a project has at least one of:

• An Epic with a valid due date (Epic.fields.duedate), or
• A Release (version) with a releaseDate.

4. Saved Views — Behavior & Scope

Save new view opens a modal where you enter a view name and choose a scope:

• Everyone — saved globally; appears in the Everyone list for all users.
• Only me — saved under your user key; visible only to you.

Each saved view stores:

How a view loads

• Projects in the view (milestoneSelection === 'epics' or 'releases') appear first, ordered by projectOrder.
• All other projects still appear below, so newly created projects are always visible.
• If a project was recorded as having epics/releases when the view was saved, the app fetches full details automatically so the Use Epics / Use Releases buttons are available without extra steps.

5. Configuration Modal — Enabling & Disabling Milestones

Open Configuration → a table of all accessible projects appears. Each project row shows: Key, Name, Color, Epics, and Releases columns.

• Use Epics button appears only if the project has an Epic with a due date (or the saved view recorded hasEpics=true).
• Use Releases button appears only if the project has at least one Version (or saved view recorded hasReleases=true).

Toggling a button selects/deselects that milestone type in the in-memory view. Changes apply immediately in the UI. Use Save current view or Save new view to persist them.

6. Ordering and New Projects

• Projects with an active milestone selection appear first, in the order from projectOrder.
• All other projects appear below so newly created projects are visible even when a saved view is active.
• To permanently include a new project in a view: enable Use Epics or Use Releases for it, then click Save current view (or Save new view).

7. Owner Badge and Visibility

Saved views show a small owner label after the view name in the dropdown:

The dropdown shows only Everyone views and your personal views.

8. Timeline Controls

9. Milestone Details and Release Notes

Click a milestone diamond (♦) on the timeline to open the Milestone modal:

• For Epics: edit summary, due date, or apply a workflow transition.
• For Versions: edit name, release date, or mark released/unreleased.

The Release Notes button is available for roadmap milestones and opens a modal that aggregates linked milestones across projects. From there you can view linked tickets and print sanitized release notes.

10. Saving & Updating Views

• Save new view — creates a new view. Choose Everyone or Only me, then name it.
• Save current view — updates the currently selected saved view with the current in-memory configuration.
• When saving, the app records projectAvailability (hasEpics / hasReleases) so future loads can enable buttons for projects that have milestone data.

11. Troubleshooting — Missing Projects or Buttons

Work through the following checks in order:

A) Are you viewing a saved view?

All projects are always listed, but only view-selected projects appear at the top. If a project should be pre-selected, ensure the saved view's milestoneSelection includes it, or update and re-save the view.

B) Does the project have epics or releases?

Epics must be of issue type Epic with a duedate set. Releases must be created versions with a releaseDate. If neither exists, the project cannot produce milestones.

C) Project availability not recorded in the view

If the view was saved before the project had epics/releases, the app won't fetch details automatically. Update the view (enable epics/releases, then save) to record availability.

D) Permissions

You need Browse Projects permission to see project details. If the app cannot fetch project data due to missing permissions, the project will be excluded from the detailed list.

E) Invalid project key characters

Project keys containing unusual characters may be filtered by server validation. Confirm the project key uses only standard alphanumeric characters.

F) Quick debug endpoints

GET /rest/api/3/project/search?maxResults=1000
GET /rest/api/3/project/{PROJECT_KEY}/versions
GET /rest/api/3/search?jql=project={KEY}%20AND%20issuetype=Epic&fields=key,summary,duedate,status&maxResults=200

If any endpoint returns 401/403, consult your admin to confirm the app has the necessary permission scopes.

12. Common Workflows

A) Create a shared view for the team (Epics)

1. Open the Configuration modal.
2. Enable Use Epics for the project rows that have Epics with due dates.
3. Reorder projects if needed.
4. Click Save new view, name it, choose Everyone, and click Save.

B) Create a personal view (only you see it)

1. Configure the modal as desired.
2. Click Save new view, choose Only me, and click Save.

C) Add a new project to an existing view

1. Open the Configuration modal while the saved view is loaded.
2. Find the new project and click Use Epics or Use Releases.
3. Click Save current view.

13. Known Limitations & Notes

• Milestones require Epic due dates or Version release dates to appear on the timeline.
• The app records projectAvailability when saving a view so future loads can enable buttons even for projects that weren't selected at save time.
• No automatic migration from older storage schemas is performed; old saved-view keys created before an owner-key change remain untouched unless migrated explicitly.
• For large project sets, the app lazy-fetches details per saved-view configuration; toggling a project's selection may trigger an on-demand fetch.