How to Submit a Pull Request to the Free Programming Books Repository: A Complete Guide

To submit a pull request to the Free Programming Books repository, fork the repository, create a feature branch, edit the appropriate markdown file in the books/ directory following the formatting guidelines in docs/CONTRIBUTING.md, and open a pull request that passes the automated linter and URL validation checks.

Contributing to the EbookFoundation/free-programming-books repository helps maintain one of the most comprehensive curated collections of free programming resources available. When you submit a pull request to add a new book or fix an existing entry, following the established workflow ensures your contribution meets the project's quality standards and passes automated validation. This guide walks through the complete process from initial setup to addressing CI check failures.

Prerequisites and Initial Setup

Before writing any code, you must understand the project's requirements and create your development environment.

Review the Contribution Guidelines

Every contribution must adhere to the standards defined in docs/CONTRIBUTING.md. This document specifies which resources are accepted, how to format entries with proper dashes and spacing, and licensing requirements. The docs/HOWTO.md file provides a quick-start overview with links to GitHub documentation for newcomers who need additional guidance on using Git.

Fork and Clone the Repository

Start by creating your own copy of the repository under your GitHub account, then download it locally.

# Clone your fork (replace <your-username> with your GitHub handle)

git clone https://github.com/<your-username>/free-programming-books.git
cd free-programming-books

Preparing Your Changes

Once you have the repository locally, isolate your work and make the necessary edits.

Create a Feature Branch

Never commit directly to the main branch. Instead, create a descriptive branch name that reflects your change.

git checkout -b add-rust-book

Edit the Appropriate Markdown File

Locate the specific markdown file that corresponds to the language or category you are updating. For example, add English books to books/free-programming-books-en.md, or find the relevant file for other languages in the books/ directory.

Follow the exact formatting rules from the contribution guide: use proper dash spacing, maintain alphabetical order, and include the title, author, format (PDF, HTML, etc.), and license when applicable.

Follow Formatting Standards

The repository requires strict formatting to ensure consistency. Entries must follow the pattern:

* [Title](URL) - Author (Format) (License)

Maintain alphabetical order within sections. Incorrect spacing or ordering will cause the automated checks to fail.

Validating Your Changes Locally

While optional, running the linter before submitting prevents common rejection reasons.

Run the Linter (Optional but Recommended)

The repository includes a linter that checks alphabetization and formatting. If you have Node.js installed, you can validate your changes locally:

npm install
npm run lint

This runs the same checks defined in .github/workflows/fpb-lint.yml that will execute when you open your pull request.

Submitting the Pull Request

After validating your work, commit the changes and open the pull request for review.

Commit and Push Your Changes

Write a clear, descriptive commit message that explains what you added or fixed.

git add books/free-programming-books-en.md
git commit -m "Add New Python Book – Jane Doe (PDF) (CC BY)"
git push origin add-rust-book

Open the Pull Request on GitHub

Navigate to your fork on GitHub, select your feature branch, and click New Pull Request. The repository provides a PR template that prompts you to describe your change. Include a brief rationale and links to the original resource or any relevant discussions.

Address Automated Check Failures

Once submitted, GitHub Actions runs the repository's linter and URL validator against your changes. If checks fail, click Details on the failed check to see the specific error. Common issues include formatting violations, alphabetization errors, or dead URLs. Fix the issue locally, commit the correction, and push to the same branch—the pull request will update automatically.

Summary

• Review docs/CONTRIBUTING.md before starting to ensure your resource meets acceptance criteria and formatting standards.
• Fork and clone the repository, then create a descriptive feature branch to isolate your changes.
• Edit the appropriate file in the books/ directory, maintaining strict alphabetical order and formatting rules.
• Validate locally using npm run lint to catch formatting errors before submitting.
• Commit with clear messages and push to your fork, then open a pull request that passes the automated checks in .github/workflows/fpb-lint.yml.

Frequently Asked Questions

What file should I edit when adding a new book?

Locate the markdown file in the books/ directory that corresponds to the language of the resource. For English books, edit books/free-programming-books-en.md. For other languages, find the appropriate free-programming-books-<language-code>.md file. Always place your entry in the correct alphabetical position within the relevant section.

Why did the automated checks fail on my pull request?

The GitHub Actions workflow defined in .github/workflows/fpb-lint.yml runs a linter that validates formatting, alphabetization, and URL accessibility. Common failures include incorrect dash spacing in entries, resources listed out of alphabetical order, or dead links. Click the Details link next to the failed check to view the specific error message and file location.

Can I submit a pull request without running the linter locally?

Yes, you can submit a pull request without local validation, but running npm install && npm run lint before pushing significantly reduces the chance of CI failures. Local linting catches formatting and alphabetization errors immediately, allowing you to fix issues before maintainers review your contribution.

How should I format my commit message?

Write clear, descriptive commit messages that explain what you added or changed. A good format includes the action (Add, Fix, Update), the resource title, and relevant metadata such as author, format, or license. For example: Add Python Data Science Handbook – Jake VanderPlas (PDF) (CC BY).

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