# How to Submit a Pull Request to the Free Programming Books Repository: A Complete Guide > Learn how to submit a pull request to the freeProgrammingBooks repository. Follow our step-by-step guide to add your contributions and improve the resource. - Repository: [Free Ebook Foundation/free-programming-books](https://github.com/EbookFoundation/free-programming-books) - Tags: how-to-guide - Published: 2026-02-23 --- **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`](https://github.com/EbookFoundation/free-programming-books/blob/main/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`](https://github.com/EbookFoundation/free-programming-books/blob/main/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`](https://github.com/EbookFoundation/free-programming-books/blob/main/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. ```bash # Clone your fork (replace with your GitHub handle) git clone https://github.com//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. ```bash 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`](https://github.com/EbookFoundation/free-programming-books/blob/main/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: ```markdown * [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: ```bash npm install npm run lint ``` This runs the same checks defined in [`.github/workflows/fpb-lint.yml`](https://github.com/EbookFoundation/free-programming-books/blob/main/.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. ```bash 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`](https://github.com/EbookFoundation/free-programming-books/blob/main/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`](https://github.com/EbookFoundation/free-programming-books/blob/main/.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`](https://github.com/EbookFoundation/free-programming-books/blob/main/books/free-programming-books-en.md). For other languages, find the appropriate `free-programming-books-.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`](https://github.com/EbookFoundation/free-programming-books/blob/main/.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)`.