Developer Roadmap Contribution Workflow: How to Submit and Review Content

The Developer Roadmap project uses a structured Git-based workflow where contributors fork the repository, add content under src/data/roadmaps/, and submit pull requests that undergo automated checks and manual maintainer review before merging.

The kamranahmedse/developer-roadmap repository maintains strict quality standards for its educational content while remaining accessible to first-time contributors. Understanding the complete contributor submission and content review workflow ensures your changes move efficiently from initial idea to production deployment.

Stages of the Contributor Submission Workflow

Planning Your Contribution

Before writing any code, contributors must determine the scope of their proposed changes. The project accepts four primary contribution types: new roadmaps, updates to existing roadmaps, project additions, and individual topic content. For substantial changes like new roadmaps or major node restructuring, contributors must first open an issue using the Roadmap Contribution template located at .github/ISSUE_TEMPLATE/04-roadmap-contribution.yml. Minor fixes such as typo corrections can proceed directly to a pull request without prior issue creation.

The contribution guidelines in contributing.md specify that each pull request should contain a single logical change. The documentation explicitly states that all files belonging to one topic must be submitted in a single PR to simplify the review process.

Setting Up the Development Environment

Contributors begin by forking the repository through the GitHub UI, then cloning their fork locally:

git clone git@github.com:YOUR_USERNAME/developer-roadmap.git
cd developer-roadmap
git checkout -b <branch-name>

While optional, running local checks prevents rework during review. Install dependencies and start the development server with:

pnpm install
pnpm dev

This opens a local preview at http://localhost:3000, allowing contributors to verify markdown rendering before submission.

Adding Content Following the Style Guide

All topic content resides in src/data/roadmaps/<roadmap>/content/ as markdown files. The format is strictly enforced: a title, a short descriptive paragraph, and a list of up to eight resources. Each resource must use a specific @type@ prefix from the allowed set: @official@, @opensource@, @article@, @course@, @podcast@, @video@, or @book@.

For example, a valid content file for React Native basics would follow this structure:

# React Native Basics

React Native lets you build native mobile apps using JavaScript and React.

Visit the following resources to learn more:

- @official@React Native Official Docs (https://reactnative.dev/)
- @article@Getting Started with React Native (https://blog.example.com/react-native-start)
- @video@React Native Tutorial – Build a Todo App (https://youtu.be/example)

Violations of the eight-resource limit or incorrect @type@ prefixes will trigger automated check failures.

Submitting Changes via Pull Request

After committing changes with meaningful messages, push the feature branch and open a pull request targeting the master branch. The PR description should reference any related issue and include the mandatory checklist:

- [ ] Content follows the markdown style guide
- [ ] No more than 8 links, each with correct @type@
- [ ] No self-promotion or external advertisement
- [ ] Tested locally (`pnpm dev`) – no rendering errors

The Content Review Process

Automated CI Checks

Upon submission, GitHub Actions workflows in .github/workflows/ execute linting, snapshot testing, and asset generation. These automated gates verify that markdown syntax complies with project standards and that no build errors exist. The deployment.yml workflow and related CI pipelines run these validation steps before human review begins.

Maintainer Review Criteria

Maintainers manually verify that submissions adhere to the no self-promotion policy, rejecting PRs created solely to market personal blogs or products. They confirm that content follows the strict markdown format and that all @type@ prefixes match the allowed link categories. If changes are required, maintainers request modifications through GitHub's review interface; contributors update their branch and push additional commits, triggering re-checks.

Once approved, maintainers merge the PR and the scripts/sync-content-to-repo.ts script propagates changes to the live site as part of the CI pipeline.

Complete Workflow Example

The following terminal commands demonstrate the end-to-end process for adding React Native resources:

# Fork the repo on GitHub, then clone your fork

git clone git@github.com:YOUR_USERNAME/developer-roadmap.git
cd developer-roadmap

# Create a feature branch

git checkout -b add-react-native-resources

# Create the content file with proper formatting

cat <<'EOF' > src/data/roadmaps/react-native/content/add-react-native.md

# React Native Basics

React Native lets you build native mobile apps using JavaScript and React.

Visit the following resources to learn more:

- @official@React Native Official Docs (https://reactnative.dev/)
- @article@Getting Started with React Native (https://blog.example.com/react-native-start)
- @video@React Native Tutorial – Build a Todo App (https://youtu.be/example)
EOF

# Verify locally (optional but recommended)

pnpm install
pnpm dev

# Commit and push

git add src/data/roadmaps/react-native/content/add-react-native.md
git commit -m "feat: add React Native basics resources"
git push origin add-react-native-resources

# Open PR via GitHub UI targeting upstream master

Summary

• Scope planning determines whether you need an issue first or can proceed directly to a PR.
• Content location is strictly under src/data/roadmaps/<roadmap>/content/ with enforced markdown formatting.
• Resource limits allow maximum eight links per topic using only approved @type@ prefixes.
• Quality gates include automated CI checks in .github/workflows/ and manual maintainer review for style compliance and self-promotion violations.
• Single PR policy requires grouping all related files for one topic into one pull request.

Frequently Asked Questions

Do I need to open an issue before submitting a pull request?

For new roadmaps or major node changes, yes—you must use the .github/ISSUE_TEMPLATE/04-roadmap-contribution.yml template to propose your idea first. Simple typo fixes and minor content updates can skip the issue phase and proceed directly to a pull request.

What file format should I use for roadmap content?

All topic files must be markdown (.md) stored in src/data/roadmaps/<roadmap>/content/. The file requires a heading, descriptive paragraph, and a resource list where each item uses an @type@ prefix such as @official@, @article@, or @video@ before the link text.

How many resources can I add to a single topic?

The style guide limits each topic to eight resources maximum. Exceeding this limit or omitting the required @type@ prefixes will result in automated check failures during the CI pipeline.

What happens after I submit my pull request?

GitHub Actions run automated linting and build checks defined in .github/workflows/. If automated checks pass, maintainers review for content quality, verify no self-promotion exists, and ensure adherence to the single-PR-per-topic policy. Approved PRs merge into master, triggering scripts/sync-content-to-repo.ts to deploy changes to the live site.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}