# Developer Roadmap Contribution Workflow: How to Submit and Review Content

> Learn the developer roadmap contribution workflow. Fork the repo, add content, and submit pull requests for review. Follow our structured Git process to contribute.

- Repository: [Kamran Ahmed/developer-roadmap](https://github.com/kamranahmedse/developer-roadmap)
- Tags: how-to-guide
- Published: 2026-02-24

---

**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`](https://github.com/kamranahmedse/developer-roadmap/blob/main/.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`](https://github.com/kamranahmedse/developer-roadmap/blob/main/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:

```bash
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:

```bash
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:

```markdown

# 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`](https://github.com/kamranahmedse/developer-roadmap/blob/main/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`](https://github.com/kamranahmedse/developer-roadmap/blob/main/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:

```bash

# 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`](https://github.com/kamranahmedse/developer-roadmap/blob/main/.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`](https://github.com/kamranahmedse/developer-roadmap/blob/main/scripts/sync-content-to-repo.ts) to deploy changes to the live site.