Feedback
Log inStart Free
← Back to Blog
2024-01-15

The Developer's Guide to Building a Public Roadmap (With GitHub Integration)

Build a developer-friendly public roadmap with GitHub integration, GraphQL APIs, and React components. Practical patterns, code examples, and best practices for technical teams.

If you're building tools for developers, your public roadmap needs to speak their language. That means more than just listing features—it means integrating with the workflows developers already use, providing API access for automation, and eliminating the marketing fluff.

Developer audiences have unique expectations. They want technical detail, not vague promises. They expect to access roadmap data programmatically through APIs. They want to see real GitHub issues and pull requests, not sanitized summaries. Most importantly, they can detect marketing speak from a mile away.

This guide covers everything you need to build a public roadmap that developers will actually use: choosing between GitHub-native approaches versus dedicated tools, implementing two-way sync with GitHub, and embedding roadmap widgets in your documentation.

Whether you're maintaining an open source project, building a commercial developer tool, or running an engineering-led product team, you'll find practical patterns and code examples to implement immediately.

Developer Audience Expectations

Before diving into implementation, let's establish what makes developer audiences different from typical SaaS users:

Technical Detail Level

Developers want to know how something will work, not just what it will do. Instead of "Improved performance," they expect "Reduced API response time from 200ms to 50ms by implementing Redis caching for frequently accessed resources."

Your roadmap should include:

  • Architectural decisions and tradeoffs
  • Technical dependencies ("Requires migration to Postgres 15")
  • Breaking changes and migration paths
  • Performance metrics and benchmarks
  • Security implications

Integration with Existing Workflows

Developers live in GitHub, GitLab, Linear, or Jira. They don't want to context-switch to another tool just to check your roadmap. Your roadmap should:

  • Link directly to GitHub issues and PRs
  • Auto-update when issues are closed or PRs are merged
  • Support subscribing to updates via RSS, webhooks, or API
  • Allow voting without creating yet another account

API Access for Automation

Developer tools should have developer-friendly APIs. Period. Your roadmap should expose:

  • Read access to browse planned features
  • Write access to submit feedback programmatically
  • Webhook notifications for status changes
  • GraphQL endpoints for flexible queries

This enables developers to build custom integrations, embed roadmap data in their own tools, and automate workflows.

Transparency About Technical Decisions

Developers respect transparency. If you're deprioritizing a feature, explain why. If a feature is blocked on an upstream dependency, say so. If you're choosing one approach over another, share the reasoning.

Common patterns:

  • RFC (Request for Comments) documents linked from roadmap items
  • Architecture Decision Records (ADRs) for major technical choices
  • Public GitHub discussions about tradeoffs
  • Status labels like "Blocked by API redesign" instead of generic "Planned"

No Marketing Fluff

"Revolutionize your workflow" and "game-changing innovation" trigger developer allergies. Stick to clear, technical language:

  • Bad: "Next-generation AI-powered insights"
  • Good: "Query analysis using GPT-4 with 30s timeout"
  • Bad: "Seamless integration"
  • Good: "OAuth 2.0 integration with automatic token refresh"

Three Roadmap Approaches for Developer Tools

There are three main approaches to building a public roadmap for developer-focused products. Each has distinct tradeoffs in cost, flexibility, and maintenance effort.

Option 1: GitHub-Native Roadmap

Use GitHub Projects (or GitLab/Bitbucket equivalents) as your public roadmap.

How it works:

  • Create a public GitHub repository (or use your existing one)
  • Enable GitHub Projects with a roadmap view
  • Create issues for planned features
  • Tag issues with labels: planned, in-progress, shipped
  • Let users comment on and upvote issues (using reactions)

✅ Pros:

  • Free and built into GitHub
  • Developers are already familiar with the interface
  • Direct linking between roadmap items and implementation PRs
  • Natural fit for open source projects
  • No additional tools to maintain

❌ Cons:

  • Limited presentation options (no custom branding)
  • GitHub reactions aren't true voting (no prioritization insight)
  • No analytics or aggregation features
  • Can't easily embed in marketing site or docs
  • Clutters your issue tracker if you use it for bugs too

Best for:

  • Open source projects
  • Small teams with developer-only users
  • Projects already using GitHub Issues extensively
  • Teams that value simplicity over customization

Example: Many successful CLI tools and libraries use this approach—they maintain a roadmap.md file in their repository or use a public GitHub Project board that anyone can view and comment on.

Option 2: Dedicated Tool + GitHub Sync

Use a dedicated feedback/roadmap tool that syncs with GitHub.

How it works:

  • Use a feedback tool like [Product] that provides a user-friendly roadmap interface
  • Configure two-way sync with GitHub
  • When users submit feedback, optionally create corresponding GitHub issues
  • When issues are closed or PRs are merged, automatically update roadmap status
  • Users see a polished roadmap; developers see familiar GitHub issues

✅ Pros:

  • Better UX for non-developer stakeholders (customers, sales, support)
  • Proper voting and prioritization features
  • Analytics: which features have most demand, who's requesting what
  • Can embed roadmap widget in docs or product
  • Keep bugs separate from feature requests
  • Aggregate feedback from multiple sources (email, chat, API)

❌ Cons:

  • Another tool to pay for and maintain
  • Integration complexity (requires OAuth, webhooks, or API keys)
  • Potential for sync conflicts if not configured properly
  • Must balance "marketing-friendly" vs "developer-friendly" presentation

Best for:

  • Commercial developer tools with diverse stakeholders
  • Teams that need voting and prioritization insights
  • Products that want to embed roadmap in docs or marketing site
  • Teams that collect feedback from non-technical users

Example: Many successful developer tools take this approach—Linear for Linear, Raycast for Raycast, Vercel's feedback portal.

Option 3: Custom-Built Roadmap

Build your own roadmap interface using your product's API.

How it works:

  • Use a headless feedback tool or build your own backend
  • Query roadmap data via GraphQL or REST API
  • Build custom UI in React/Vue/Svelte
  • Fully control presentation, filtering, and embedding

✅ Pros:

  • Complete control over UX and branding
  • Can implement exactly the features you need
  • No "powered by" badges or branding constraints
  • Perfect integration with your design system
  • Can combine with other data sources (docs, changelog, etc.)

❌ Cons:

  • Significant development and maintenance effort
  • Must build your own voting, authentication, spam prevention
  • Ongoing work to keep it updated and bug-free
  • May distract from core product development

Best for:

  • Large teams with dedicated design/engineering resources
  • Products with very specific roadmap requirements
  • Teams that want to differentiate on roadmap UX itself
  • Companies that already have in-house tools for everything

Example: Some larger companies like Stripe and Figma have custom-built feedback and roadmap systems deeply integrated into their products.

GitHub Integration Deep Dive

If you choose Option 2 (dedicated tool + GitHub sync), here's how to implement it effectively. This approach combines the polish of a dedicated feedback tool with the technical transparency of GitHub issues.

Key Benefit: Your users get a user-friendly voting interface while your developers work in GitHub—the best of both worlds.

Syncing Feedback Items to GitHub Issues

The most common pattern is to create a GitHub issue whenever a feature request reaches a certain threshold (votes, internal priority, or manual approval).

Workflow:

  1. User submits feature request via your feedback tool
  2. Feature request accumulates votes or gets prioritized internally
  3. When ready for development, create corresponding GitHub issue
  4. Link the two: issue URL stored in feedback tool, feedback URL in issue description
  5. Developers work in GitHub as usual
  6. Status changes in GitHub propagate back to feedback tool

Implementation: Most feedback tools provide a "Create GitHub Issue" action. In [Product], this looks like:

// Via GraphQL API
mutation CreateGitHubIssue {
  createGitHubIssue(
    feedbackItemId: "123"
    repository: "your-org/your-repo"
    title: "Add dark mode support"
    labels: ["feature-request", "ui"]
  ) {
    issueUrl
    issueNumber
  }
}

Or via CLI:

feedback github create --item=123 --repo=your-org/your-repo

The issue description should include:

  • Link back to the feedback item
  • Number of votes and key user quotes
  • Use cases and context from feedback

Example issue template:

**Feature Request:** [Link to feedback item]
**Votes:** 47 | **Status:** Planned

## Problem
Users want to use our CLI in environments with dark terminals...

## Proposed Solution
Add a `--theme` flag that accepts `light`, `dark`, or `auto`...

## Context
- 47 users have voted for this
- Top use case: using CLI in tmux/iTerm with dark themes
- Related to issue #234 (color output improvements)

---
*This issue was created from user feedback. Vote and comment on the [feedback item].*

Linking Roadmap Items to PRs

When development starts, link the PR to both the GitHub issue and the feedback item:

Closes #456
Feedback: https://feedback.yourproduct.com/item/123

Your feedback tool can detect these references (via webhooks or periodic API polling) and automatically:

  • Update status to "In Progress" when PR is opened
  • Update status to "Shipped" when PR is merged
  • Add PR link to the feedback item
  • Notify voters that the feature is being worked on

Auto-Updating Status from GitHub

Use GitHub webhooks to push status changes to your feedback tool in real-time:

GitHub Webhook Configuration:

  • Payload URL: https://api.yourfeedbacktool.com/webhooks/github
  • Events: Issues, Pull Requests, Releases
  • Content type: application/json

Webhook handler logic:

// Simplified webhook handler
app.post('/webhooks/github', async (req, res) => {
  const { action, issue, pull_request } = req.body;

  // Extract feedback item ID from issue/PR description
  const feedbackMatch = issue?.body?.match(/feedback\.yourproduct\.com\/item\/(\d+)/);
  if (!feedbackMatch) return res.status(200).send('No feedback link');

  const feedbackItemId = feedbackMatch[1];

  // Update status based on action
  if (action === 'closed' && issue?.state === 'closed') {
    await updateFeedbackStatus(feedbackItemId, 'COMPLETED');
  } else if (action === 'opened' && pull_request) {
    await updateFeedbackStatus(feedbackItemId, 'IN_PROGRESS');
    await addComment(feedbackItemId, `Development started: ${pull_request.html_url}`);
  } else if (action === 'closed' && pull_request?.merged) {
    await updateFeedbackStatus(feedbackItemId, 'SHIPPED');
    await notifyVoters(feedbackItemId);
  }

  res.status(200).send('OK');
});

Workflow Examples

Example 1: Feature Request to Shipped

  1. User submits: "Add support for .env file loading"
  2. Request gets 30 votes over 2 weeks
  3. PM creates GitHub issue #789 with link to feedback item
  4. Developer opens PR #791 referencing issue #789
  5. Feedback status auto-updates to "In Progress"
  6. PR merged, tagged in release v2.3.0
  7. Feedback status auto-updates to "Shipped in v2.3.0"
  8. All 30 voters get email notification

Example 2: GitHub Action for Auto-Sync

You can also use GitHub Actions to sync status changes:

# .github/workflows/sync-roadmap.yml
name: Sync to Roadmap

on:
  issues:
    types: [closed, reopened]
  pull_request:
    types: [opened, closed]

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - name: Extract feedback URL
        id: extract
        run: |
          FEEDBACK_URL=$(echo "${{ github.event.issue.body || github.event.pull_request.body }}" | grep -oP 'feedback\.yourproduct\.com/item/\K\d+')
          echo "feedback_id=$FEEDBACK_URL" >> $GITHUB_OUTPUT

      - name: Update feedback status
        if: steps.extract.outputs.feedback_id != ''
        run: |
          curl -X POST https://api.yourfeedbacktool.com/graphql \
            -H "Authorization: Bearer ${{ secrets.FEEDBACK_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{
              "query": "mutation { updateStatus(id: \"${{ steps.extract.outputs.feedback_id }}\", status: SHIPPED) { id } }"
            }'

API-First Roadmap Management

Developer tools should expose their roadmap data via API. This enables custom integrations, automation, and embedding.

Why APIs Matter for Developer Tools

Developer audiences expect to access your roadmap programmatically for:

  • Building custom dashboards that combine roadmap + usage data
  • Automating notifications (Slack bot that posts roadmap updates)
  • Filtering roadmap by tags/labels relevant to their use case
  • Embedding roadmap in internal wikis or tools
  • Fetching data for analysis (which features are most requested?)

Without an API, developers will scrape your HTML or give up.

GraphQL vs REST for Roadmap Data

GraphQL advantages:

  • Clients request exactly the fields they need
  • Single endpoint, flexible queries
  • Strong typing with schema introspection
  • Easier to add fields without breaking existing clients

REST advantages:

  • Simpler to implement and understand
  • Better HTTP caching
  • Familiar to more developers

For roadmap data, GraphQL is generally preferred because:

  • Queries are naturally hierarchical (roadmap → items → votes → users)
  • Clients have different needs (some want full detail, others just titles)
  • You'll likely expand the schema over time

Example GraphQL schema for roadmap:

type Query {
  roadmap: Roadmap!
  roadmapItem(id: ID!): RoadmapItem
}

type Roadmap {
  items(status: Status, tag: String, orderBy: OrderBy): [RoadmapItem!]!
  tags: [String!]!
}

type RoadmapItem {
  id: ID!
  title: String!
  description: String!
  status: Status!
  votes: Int!
  createdAt: DateTime!
  updatedAt: DateTime!
  tags: [String!]!
  githubIssue: GitHubIssue
  comments: [Comment!]!
}

type GitHubIssue {
  url: String!
  number: Int!
  state: String!
}

enum Status {
  PLANNED
  IN_PROGRESS
  SHIPPED
  DECLINED
}

enum OrderBy {
  VOTES
  RECENT
  TRENDING
}

Example: Fetching Roadmap Data via GraphQL

Get all in-progress items:

const query = `
  query GetInProgressItems {
    roadmap {
      items(status: IN_PROGRESS, orderBy: VOTES) {
        id
        title
        votes
        githubIssue {
          url
          number
        }
      }
    }
  }
`;

const response = await fetch('https://api.yourfeedbacktool.com/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${API_KEY}`,
  },
  body: JSON.stringify({ query }),
});

const data = await response.json();
console.log(data.data.roadmap.items);

Get detailed info for a specific item:

const query = `
  query GetRoadmapItem($id: ID!) {
    roadmapItem(id: $id) {
      id
      title
      description
      status
      votes
      tags
      createdAt
      githubIssue {
        url
        number
        state
      }
      comments {
        author
        content
        createdAt
      }
    }
  }
`;

const response = await fetch('https://api.yourfeedbacktool.com/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${API_KEY}`,
  },
  body: JSON.stringify({
    query,
    variables: { id: '123' },
  }),
});

Example: Building a Roadmap Widget

With a GraphQL API, you can build custom embeds:

// roadmap-widget.ts
async function fetchRoadmapData() {
  const query = `
    query GetRoadmap {
      roadmap {
        items(status: PLANNED, orderBy: VOTES) {
          id
          title
          votes
          tags
        }
      }
    }
  `;

  const res = await fetch('https://api.yourfeedbacktool.com/graphql', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ query }),
  });

  const { data } = await res.json();
  return data.roadmap.items;
}

function renderRoadmap(items) {
  const container = document.getElementById('roadmap');
  container.innerHTML = items.map(item => `
    <div class="roadmap-item">
      <h3>${item.title}</h3>
      <span class="votes">${item.votes} votes</span>
      <div class="tags">
        ${item.tags.map(tag => `<span class="tag">${tag}</span>`).join('')}
      </div>
    </div>
  `).join('');
}

fetchRoadmapData().then(renderRoadmap);

CLI for Roadmap Updates

Developer tools should be controllable from the terminal. A CLI for roadmap management enables scripting, automation, and integration with existing workflows.

Updating Roadmap from Terminal

Basic CLI operations:

# List roadmap items
$ feedback roadmap list
$ feedback roadmap list --status=in-progress
$ feedback roadmap list --tag=api

# Get details for a specific item
$ feedback roadmap get --item=123

# Update item status
$ feedback roadmap update --item=123 --status=shipped

# Add comment
$ feedback roadmap comment --item=123 --message="ETA: Q2 2024"

# Create new item
$ feedback roadmap create \
  --title="Add webhooks support" \
  --description="..." \
  --tags=api,integration

Automating Status Changes

Example: Update status when deploying:

#!/bin/bash
# deploy.sh

# Deploy application
./deploy-production.sh

# Mark features as shipped
feedback roadmap update --item=123 --status=shipped --version="v2.5.0"
feedback roadmap update --item=124 --status=shipped --version="v2.5.0"

# Notify team
echo "Deployed v2.5.0 with 2 new features"

Example: Daily roadmap summary:

#!/bin/bash
# daily-summary.sh (run via cron)

echo "=== Roadmap Summary ==="
echo ""

echo "In Progress ($(feedback roadmap list --status=in-progress --count)):"
feedback roadmap list --status=in-progress --format=compact

echo ""
echo "Shipped This Week:"
feedback roadmap list --status=shipped --since=7d --format=compact

echo ""
echo "Top Requested:"
feedback roadmap list --status=planned --order=votes --limit=5

Integration with CI/CD

Example: GitHub Actions workflow that updates roadmap on release:

# .github/workflows/release.yml
name: Release

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Create release
        run: |
          # Create GitHub release
          gh release create ${{ github.ref_name }} --generate-notes

      - name: Update roadmap
        run: |
          # Install CLI
          npm install -g @yourproduct/feedback-cli

          # Mark features in this release as shipped
          # (Assumes git commit messages include "Closes feedback:123" format)
          git log $(git describe --tags --abbrev=0 HEAD^)..HEAD --oneline \
            | grep -oP 'feedback:\K\d+' \
            | xargs -I {} feedback roadmap update --item={} --status=shipped --version=${{ github.ref_name }}

Example: Slack bot integration:

// slack-bot.ts
import { WebClient } from '@slack/web-api';
import { exec } from 'child_process';
import { promisify } from 'util';

const execAsync = promisify(exec);
const slack = new WebClient(process.env.SLACK_TOKEN);

// Listen for commands like "/roadmap in-progress"
app.command('/roadmap', async ({ command, ack, say }) => {
  await ack();

  const { stdout } = await execAsync(`feedback roadmap list --status=${command.text} --format=json`);
  const items = JSON.parse(stdout);

  const blocks = items.map(item => ({
    type: 'section',
    text: {
      type: 'mrkdwn',
      text: `*${item.title}*\n${item.votes} votes • ${item.tags.join(', ')}`,
    },
  }));

  await say({ blocks });
});

React/Vue Components for Embedding

Pre-built components make it easy to embed roadmap data in your docs, marketing site, or product UI.

Embedding Roadmap in Documentation

Example: React component for docs site:

// components/RoadmapWidget.tsx
import { RoadmapWidget } from '@yourproduct/react-feedback';
import '@yourproduct/react-feedback/dist/styles.css';

export default function DocsRoadmap() {
  return (
    <div className="roadmap-section">
      <h2>What's Coming Next</h2>
      <p>Here's what we're working on. Vote on features you'd like to see!</p>

      <RoadmapWidget
        apiKey={process.env.NEXT_PUBLIC_FEEDBACK_API_KEY}
        projectId="your-project"
        statuses={['planned', 'in-progress']}
        theme="light"
        showVotes={true}
        allowVoting={true}
        maxItems={10}
      />
    </div>
  );
}

Embedding in Product UI

Example: In-app roadmap widget:

// components/InAppRoadmap.tsx
import { useState, useEffect } from 'react';
import { useFeedback } from '@yourproduct/react-feedback';

export default function InAppRoadmap() {
  const { roadmapItems, loading, vote } = useFeedback({
    projectId: 'your-project',
    apiKey: process.env.REACT_APP_FEEDBACK_API_KEY,
  });

  const [filter, setFilter] = useState('all');

  const filteredItems = filter === 'all'
    ? roadmapItems
    : roadmapItems.filter(item => item.status === filter);

  if (loading) return <div>Loading roadmap...</div>;

  return (
    <div className="in-app-roadmap">
      <div className="filters">
        <button onClick={() => setFilter('all')}>All</button>
        <button onClick={() => setFilter('planned')}>Planned</button>
        <button onClick={() => setFilter('in-progress')}>In Progress</button>
        <button onClick={() => setFilter('shipped')}>Shipped</button>
      </div>

      <div className="items">
        {filteredItems.map(item => (
          <div key={item.id} className="item">
            <h3>{item.title}</h3>
            <p>{item.description}</p>
            <div className="meta">
              <span className={`status ${item.status}`}>{item.status}</span>
              <button onClick={() => vote(item.id)}>
                👍 {item.votes}
              </button>
            </div>
          </div>
        ))}
      </div>
    </div>
  );
}

Customization Options

Good widget libraries expose customization props:

<RoadmapWidget
  // Data source
  projectId="your-project"
  apiKey="..."

  // Display options
  theme="dark"              // 'light' | 'dark' | 'auto'
  layout="grid"             // 'list' | 'grid' | 'kanban'
  maxItems={10}

  // Filtering
  statuses={['planned', 'in-progress']}
  tags={['api', 'cli']}
  orderBy="votes"           // 'votes' | 'recent' | 'trending'

  // Features
  showVotes={true}
  allowVoting={true}
  showComments={true}
  showGitHubLinks={true}

  // Styling
  className="custom-roadmap"
  primaryColor="#6366f1"

  // Callbacks
  onVote={(itemId) => console.log('Voted:', itemId)}
  onItemClick={(item) => console.log('Clicked:', item)}
/>

Vue 3 example:

<template>
  <RoadmapWidget
    :project-id="projectId"
    :api-key="apiKey"
    theme="dark"
    :statuses="['planned', 'in-progress']"
    :show-votes="true"
    :allow-voting="true"
    @vote="handleVote"
  />
</template>

<script setup>
import { RoadmapWidget } from '@yourproduct/vue-feedback';

const projectId = 'your-project';
const apiKey = import.meta.env.VITE_FEEDBACK_API_KEY;

function handleVote(itemId) {
  console.log('User voted on:', itemId);
}
</script>

Real Examples: Developer Tool Roadmaps

Let's look at how successful developer tools approach public roadmaps.

Linear's Public Roadmap

URL: linear.app/roadmap

What they do well:

  • Clean, on-brand design that matches their product
  • Clear status labels: "In Progress," "Planned," "Launched"
  • Each item links to a detailed page with updates and comments
  • Voting is simple (single click, no account required)
  • Items show which team is working on them
  • Regular status updates from the team

Takeaways:

  • Keep it visually consistent with your product
  • Make voting frictionless
  • Show progress, not just "planned" forever
  • Communicate actively with voters

Vercel's Feedback Hub

URL: vercel.com/feedback

What they do well:

  • Integrated with GitHub (items link to GitHub discussions)
  • Tag-based filtering (Edge Functions, Build System, etc.)
  • Shows upvotes and comment count at a glance
  • Users can submit ideas or upvote existing ones
  • Status badges for "Shipped" items with version numbers

Takeaways:

  • GitHub integration builds trust with developer audience
  • Filtering by category helps users find relevant features
  • Celebrate shipped features prominently

Raycast's Community Feedback

URL: raycast.com/community

What they do well:

  • Very developer-focused (extensions API, CLI tools)
  • Shows "Top Requested" section prominently
  • Each feature has discussion thread
  • Clear communication when features ship
  • Community contributes extensions while waiting for core features

Takeaways:

  • Highlight most-requested features
  • Enable community contributions where possible
  • Be transparent about what's coming vs. what's not

GitHub's Public Roadmap

URL: github.com/github/roadmap

What they do well:

  • Dogfooding: GitHub uses GitHub Issues for their roadmap
  • Organized by product area and quarter
  • Each item has detailed description and rationale
  • Links to beta releases and documentation
  • Community can comment and react

Takeaways:

  • Use your own product for your roadmap (dogfooding)
  • Organize by time and category
  • Provide context and reasoning

Open Source Considerations

Open source projects have unique roadmap needs beyond commercial products.

Community Contribution Alignment

Your roadmap should help contributors understand where to focus:

  • Label items as "Good First Issue" or "Help Wanted"
  • Indicate which features need design input vs. implementation
  • Show which features are approved vs. under discussion
  • Link to RFCs or design documents

Example labels:

  • help-wanted - Community contributions welcome
  • needs-rfc - Requires design discussion first
  • breaking-change - Will require major version bump
  • good-first-issue - Suitable for new contributors

RFC Processes + Roadmap

Many successful open source projects use an RFC (Request for Comments) process:

  1. Feature proposal submitted as RFC document
  2. Community discusses tradeoffs
  3. Core team approves or requests changes
  4. Approved RFCs move to roadmap
  5. Implementation PRs reference the RFC

Example workflow:

  • User submits feature request via GitHub Issue
  • If significant, core team requests RFC document
  • RFC opened as PR in rfcs/ directory
  • Community and core team review (1-2 weeks)
  • If approved, RFC merged and GitHub Issue moves to roadmap
  • Implementation PRs reference RFC and roadmap issue

Maintainer Burnout Prevention

Public roadmaps can increase pressure on maintainers. Protect yourself:

  • Set clear expectations: "Roadmap items are not commitments"
  • Use "Under Consideration" status for unconfirmed ideas
  • Be honest about capacity: "2-3 major features per quarter"
  • Decline politely: Not every feature request belongs on the roadmap
  • Share the load: Invite community co-maintainers

Balancing Community Wants vs. Project Vision

Not every highly-voted feature is right for your project:

  • Some requests are better suited for plugins/extensions
  • Some features conflict with core principles
  • Some features would bloat the project scope

How to handle mismatches:

  • Explain why a feature doesn't fit (don't just ignore it)
  • Suggest alternatives or workarounds
  • Consider plugin architecture to enable community extensions
  • Point to other projects that might be better fits

Example:

"Thanks for the suggestion! We've decided not to add built-in authentication to [Project] because it would significantly increase complexity and maintenance burden. Instead, we recommend using [Auth Library] alongside [Project]. We've added an example to our docs."

Measuring Public Roadmap Success

How do you know if your developer roadmap is working? Track these key metrics to understand engagement and effectiveness:

Engagement Metrics

  • Active voters: Number of users who vote on features monthly
  • Submissions: New feature requests per month
  • Comments: Average comments per roadmap item
  • Repeat engagement: Users who vote on multiple features
  • Time to first vote: How quickly new users engage

Tools: Most feedback platforms provide these built-in. Alternatively, track via API and your analytics tool.

Contribution Correlation (Open Source)

  • PRs linked to roadmap items: % of PRs that reference roadmap issues
  • Contributor retention: Do contributors stick around after first PR?
  • Time to implementation: Days from "Approved" to "Shipped"
  • Community vs. core ratio: % of roadmap items implemented by community

Analysis:

-- Example query: PRs linked to roadmap
SELECT
  COUNT(DISTINCT pr.id) as total_prs,
  COUNT(DISTINCT CASE WHEN pr.body LIKE '%roadmap%' THEN pr.id END) as linked_prs,
  ROUND(100.0 * COUNT(DISTINCT CASE WHEN pr.body LIKE '%roadmap%' THEN pr.id END) / COUNT(DISTINCT pr.id), 1) as pct_linked
FROM pull_requests pr
WHERE pr.merged_at > NOW() - INTERVAL '90 days';

Community Satisfaction

  • NPS for roadmap transparency: "How satisfied are you with our product roadmap?"
  • Response time: Average time from feature ship to voter notification
  • Feedback on feedback: Comments thanking team for shipping requested features
  • Churn correlation: Do users who engage with roadmap have lower churn?

Qualitative signals:

  • Positive mentions in community forums or social media
  • Users citing roadmap when choosing your product
  • Decrease in "when will X ship?" support tickets

Leading Indicators

  • Roadmap page views: Is anyone actually looking at it?
  • Vote-to-view ratio: Do viewers engage, or just browse?
  • GitHub issue references: Are developers linking roadmap items in PRs?
  • API usage: Are developers querying roadmap data programmatically?

Benchmarks (typical ranges):

  • Vote-to-view ratio: 5-15%
  • Return engagement: 20-40% of voters vote on 2+ items
  • Submission-to-approval ratio: 10-30% of submissions reach roadmap

Conclusion

Building a public roadmap for developer audiences requires more than just listing features. Developers expect technical detail, not marketing fluff. They want integration with the tools they already use, not another silo. They need API access for automation, not just a web UI.

The three main approaches—GitHub-native, dedicated tool with GitHub sync, or custom-built—each have clear tradeoffs. For most commercial developer tools, a dedicated feedback tool with two-way GitHub integration provides the best balance of user experience, features, and maintainability.

Key Principles for Developer Roadmaps:

- Integration over isolation: Sync with GitHub, expose APIs, provide CLIs and SDKs

- Transparency over polish: Show real GitHub issues, explain tradeoffs, admit when features won't happen

- Developer experience: Make voting frictionless, enable custom embeds, provide code examples

- Signal over noise: Use voting and analytics to understand real demand, not just loud voices

Whether you're building an open source library or a commercial developer platform, your public roadmap should feel like a natural extension of your product's developer-friendly philosophy.

Ready to build a roadmap that developers actually use? [Product] provides GraphQL APIs, React/Vue components, CLI tools, and two-way GitHub sync out of the box. Start with our free tier and upgrade as you grow.

Create your developer-friendly roadmap →