Keep a Roadmap

An example

# Roadmap

Last reviewed: 2026-11-14

Tracker: [Ferry project board](https://github.com/orgs/ferry-cli/projects/1)

This is where Ferry is headed. It's a plan, not a promise: items move as we
learn more, and nothing here has a date. Work that has shipped is listed in the
[changelog](CHANGELOG.md). To suggest something, open an issue.

This roadmap follows [Keep a Roadmap 1.0.0](https://keeparoadmap.com/).

## Now

- **Windows support.** Run the same `ferry` commands on Windows, with a copy
  fallback wherever symlinks aren't allowed. [#214]
- **Faster first sync.** The first sync of a large home folder takes minutes;
  caching file hashes should bring it down to seconds. [#198]

## Next

- **Encrypted secrets.** Keep tokens and SSH config in your dotfiles repo,
  encrypted at rest and decrypted only on machines you trust. [#156]
- **Per-machine overrides.** One repo for every machine, with small differences
  for each one and no long-lived branches. [#173]
- **Plain-language errors.** Every error says what went wrong and what to try
  next, instead of printing a stack trace. [#220]

### Docs

- **Migration guides.** Step-by-step moves to Ferry from GNU Stow, chezmoi
  and yadm. [#231]

## Later

- **Package lists.** Reinstall your Homebrew, apt or winget packages on a new
  machine along with your files. [#240]
- **Sync hooks.** Run your own scripts before and after a sync. [#131]

## Not planned

- **A hosted sync service.** Ferry works with any Git remote you already have.
  Running a service would take time away from the tool itself. [#102]
- **Automatic background sync.** Syncing on every file change made conflicts
  silent and hard to undo, so syncs stay something you start. [#119]

[#102]: https://github.com/ferry-cli/ferry/issues/102
[#119]: https://github.com/ferry-cli/ferry/issues/119
[#131]: https://github.com/ferry-cli/ferry/issues/131
[#156]: https://github.com/ferry-cli/ferry/issues/156
[#173]: https://github.com/ferry-cli/ferry/issues/173
[#198]: https://github.com/ferry-cli/ferry/issues/198
[#214]: https://github.com/ferry-cli/ferry/issues/214
[#220]: https://github.com/ferry-cli/ferry/issues/220
[#231]: https://github.com/ferry-cli/ferry/issues/231
[#240]: https://github.com/ferry-cli/ferry/issues/240

The roadmap of Ferry, a made-up tool for syncing dotfiles. Its issue links are placeholders. The same file is in this convention's repository as examples/ROADMAP.md.

What is a roadmap?

A roadmap is a short file that says what a project is working on now, what it will take up next, what it means to get to later, and what it has decided not to do.

It's written for the people around the project: users, contributors, colleagues. It lives in the repository next to the code, as ROADMAP.md, so it's versioned, reviewed and read like everything else there.

Why keep a roadmap?

Because people will ask where the project is headed, and one honest answer in a known place beats a hundred partial ones scattered through issue threads and chat logs.

A roadmap lets users decide whether to wait for something or look elsewhere. It shows contributors which work is wanted. And it lets maintainers say "not now" or "no" once, in writing, with a reason.

Who needs a roadmap?

Any project that other people depend on. If someone has ever asked you "is this coming?", your project needs one.

How do I keep a good roadmap?

Guiding principles

Roadmaps are for people, not machines. Write plain sentences that anyone can read in a couple of minutes. The roadmap is not a data format or an export from a tool.
Horizons, not dates. Group work by how soon you expect to get to it, not by when you hope it will finish.
Every item links to where it's tracked. The roadmap is the summary. The issue, track or pull request holds the detail and the discussion.
Finished work leaves. When something ships, it comes off the roadmap and goes into the changelog.
Show when it was last reviewed. A "Last reviewed" date at the top tells readers how far to trust the rest of the page.
Say what you've decided not to do. Once you've considered something and dropped it, say so. A considered "no" is as useful to a reader as a "yes", and it saves you from answering the same request again.
Keep it short. A roadmap is a choice of what matters. It is not a list of everything anyone has ever asked for.

The layout

A roadmap has, in this order:

A title: # Roadmap.
A Last reviewed: line with the date of the last full review, written as year, month and day: YYYY-MM-DD.
If the project has a tracker, a Tracker: line with one link to it, as its own paragraph: Tracker: [Ferry project board](https://github.com/orgs/ferry-cli/projects/1). Leave it out if there's no tracker. See linking to your tracker.
A sentence or two saying what this roadmap covers and where shipped work is recorded.
A line saying which version of this convention it follows, with a link: This roadmap follows [Keep a Roadmap 1.0.0](https://keeparoadmap.com/).
Three sections, always these three and always in this order: Now, Next and Later.
A fourth section, Not planned, last, once you've considered something and dropped it. Leave it out until then.

If Now, Next or Later is empty, keep its heading and write "Nothing right now." under it, so readers can tell it's empty on purpose.

Inside any section, you can group items under subheadings by theme, such as ### Docs under Next. Put items that don't belong to a theme first, before any subheading. The sections themselves stay fixed: the same names, in the same order.

What goes in each section

Now: Work that is underway: someone is on it today. Keep it small. As a rule of thumb, Now should hold no more items than there are people, or teams, actively working on them.
Next: Work you've committed to starting when something in Now finishes. It's understood well enough that someone could begin. List it in the order you expect to take it up.
Later: Things you intend to do but haven't worked out yet. Later is direction more than plan, so it's fine for these items to be rough. It isn't fine for Later to become the backlog.
Not planned: Things you considered and decided against, each with a short reason. Add the section the first time you drop something; until then, leave it out. Only real decisions belong here. Ideas you simply haven't gotten to stay in your issue tracker.

Writing an item

One list item per piece of work, starting with a short name in bold.
Describe the outcome for the reader, not the task for the team: "Windows support", not "Port the filesystem layer".
Follow the name with a sentence or two on what changes and why it matters.
End with a link to where the work is tracked.
Leave out dates, owners, percentages and status badges. An item's status is the section it's in.
Within a section, put the most important or soonest item first.

Linking to your tracker

If the detail lives somewhere, such as a GitHub project board, an issue tracker, Linear, Jira or a set of milestones, point to it once, in the Tracker: line under Last reviewed. The roadmap is the few items you chose to tell people about. The tracker holds every task. The roadmap links to the tracker, but it never mirrors it.

The Tracker: line doesn't replace the link at the end of each item. The two links do different jobs. An item's link goes to the issue behind that one piece of work. The Tracker: line is for readers who want the whole picture, including everything the roadmap leaves out. Pick one place for it: a board, a filtered view or the issue list, whichever your readers can open.

Moving items

Items move toward Now as they get closer: from Later to Next, and from Next to Now.
Items can move back, too. Moving an item back is honest, not a failure. Say why in the linked issue.
When you drop an item, move it to Not planned with a reason, adding that section if this is the first. Don't delete something people were waiting for without a word.
If you change your mind about something in Not planned, move it back into Later or Next and note why in its issue.

When something ships

Remove it from Now, and record it in your changelog. If you follow Keep a Changelog, that means its Unreleased section. A roadmap never grows a "Done" section: the changelog already is one.

Reviewing

Read the whole roadmap on a regular rhythm, and whenever your priorities shift. Move what has moved, cut what no longer matters, then update the Last reviewed date. Update the date even when nothing else changed: it records that someone looked, not that something moved.

Keep Not planned items while people might still ask about them. Once nobody would, you can remove them; the linked issue stays as the record.

What makes a roadmap bad?

Dates as promises

Write "Q3" next to an item and someone will plan around it. When it slips, they stop trusting the rest of the roadmap too.

The backlog dump

Pasting every open issue into Later, or syncing them in from the tracker. A roadmap with two hundred items says nothing about priorities. Your tracker already holds the backlog, so link to it in the Tracker: line instead of copying it.

Finished items that never leave

Strikethrough, checkmarks, a "Done" heading. Shipped work belongs in the changelog, where readers look for it.

The stale roadmap

No review date, or one from two years ago. Readers can't tell whether anything on it is still true, so they assume none of it is.

Everything is Now

Ten items in Now and three people working on the project. If everything is happening, nothing is.

Items that go nowhere

An item without a link can't be followed, discussed or checked. Readers who care about it have nowhere to go.

Silent deletions

An item that people were waiting for disappears between one review and the next. Move it to Not planned and say why instead.

A task list in disguise

"Refactor ingest v2" means something to the team and nothing to anyone else. Name the outcome a reader would notice.

Frequently asked questions

How is a roadmap different from a changelog?

A changelog records what has shipped. A roadmap says what's coming. Together they make one timeline: work enters the roadmap, moves toward Now, ships, and crosses over into the changelog. Both are written for people, and both live in the repository.

Doesn't my issue tracker already do this?

Your tracker holds every task, with its detail and discussion, for the people doing the work. The roadmap is the short, curated view for everyone else. It's readable without an account or a login, it's versioned with the code, and it doesn't change unless someone decides it should. Keep the work in the tracker. Link to the tracker once in the Tracker: line, and link each item to its own issue.

What about GitHub Projects, or milestones?

Use them. A roadmap layout in GitHub Projects places items on a timeline using date and iteration fields, which is useful for planning the work. Milestones group issues and pull requests so you can see their progress. A ROADMAP.md is the plain statement you make to readers on top of all that. Put the board's link in the Tracker: line. You can draft the roadmap from the board, but have a person edit the result.

Why not generate the roadmap from the tracker?

Because choosing is the point. A generated roadmap shows whatever the tracker holds today, stale issues and all. It changes without anyone deciding it should, and soon it's the backlog dump again. Write the few items by hand, and link to the tracker for the rest.

How often should I review it?

Monthly suits most projects. Review it sooner when priorities change, and before each release, when you're already updating the changelog. If a review keeps finding nothing to change, you can review less often, but keep the date honest.

Why not dates?

Because readers take a date on a roadmap as a promise, and software estimates are rarely good enough to promise on. A horizon says what you actually know: the order you'll work in, and roughly how near each thing is.

If a date outside your control really matters, such as a dependency reaching end of life, state it as a fact in the item's description. It is a constraint you're working against, not a delivery date.

Does this work for private or internal projects?

Yes. The readers are colleagues, other teams and leadership instead of the public, but the rules are the same. Not planned is often the most useful section inside a company, because it settles questions that would otherwise come back every quarter. Items can link to an internal tracker, as long as your readers can open it.

My project is tiny. Is this overkill?

A roadmap with one item in Now and one in Not planned is a perfectly good roadmap. If nobody ever asks where the project is going, you may not need one yet.

Can I add sections, or rename these?

No. The same headings in the same order in every roadmap mean readers know where to look in any project. Now, Next and Later always appear; Not planned appears once you've dropped something.

You can group items inside a section under subheadings, such as ### Docs or ### Performance under Next. Use them for themes, not for status, owners or dates. And if a section feels too long to read even with subheadings, that's usually a sign to cut it, not to split it.

Do I need a Not planned section from the start?

No. Add it the first time you consider something and decide against it. An empty Not planned section tells readers nothing, but the first real entry in it usually answers a question people were already asking.

What should I call the file, and where should it go?

ROADMAP.md, at the root of the repository, next to README.md and CHANGELOG.md. Link to it from your README.

Versions of this convention

This page describes version 1.0.0 of Keep a Roadmap. Its version numbers follow Semantic Versioning 2.0.0:

a major version changes what a conforming roadmap looks like, such as adding, removing or renaming a required section;
a minor version adds guidance without making any conforming roadmap stop conforming;
a patch version fixes wording, typos or links.

Every roadmap says which version it follows, in the line described in the layout. When a new version comes out, update that line at your next review, once your roadmap matches it.

Inspiration and prior art

Most of what's here was borrowed. These are the sources, and what we took from each.

Keep a Changelog: By Olivier Lacan and contributors, MIT licensed. The model for this whole project: a plain Markdown file with a fixed shape, explained on one page with guiding principles, a list of bad practices and an FAQ, and versioned itself. This page follows its order of sections closely (what, why, who, how, what makes it bad, questions), and our "Finished work leaves" principle hands off to its Unreleased section. The words are our own.
Now / Next / Later: The three time horizons come from the roadmap format developed at ProdPad by Janna Bastow and Simon Cast. In “The Birth of the Modern Roadmap” (December 31, 2019), Bastow dates its first sketch to late 2012, under the names Current, Near Term and Future. In “Why I Invented the Now-Next-Later Roadmap” (October 18, 2022), she explains dropping dates for those three columns. Peter Gillard-Moss independently described a “Now, Next and Later” board at Thoughtworks in September 2012. The Not planned section and the rules for a ROADMAP.md file aren't part of the format as those posts describe it; they're ours.
Semantic Versioning: By Tom Preston-Werner, licensed CC BY 3.0. This convention's own version numbers follow it, as Keep a Changelog's do.
GitHub’s “not planned” close reason: Since May 2022, GitHub has let you close an issue as “not planned” instead of completed. We borrowed the name for our fourth section, because many readers already know what it means.
GitHub’s public roadmap: A working example of an open roadmap where every item is an issue, arranged by how far out it is. It supports our rule that every item links to where it's tracked. It places items by quarter; we chose not to.
llms.txt: A proposal by Jeremy Howard, published September 3, 2024, and kept in Answer.AI's repository under the Apache 2.0 license. The llms.txt file and the Markdown twin of this page, index.md, follow it, so agents can read the convention without parsing HTML.

GitHub Projects' roadmap layout and milestones are mentioned in the FAQ as tools that work alongside a roadmap. We didn't take ideas from them, so they aren't credited as sources.