How to Contribute to the free-programming-books Repository: A Complete Guide

To contribute to the free-programming-books repository, fork the repository on GitHub, edit the appropriate Markdown list file following the formatting rules in docs/CONTRIBUTING.md, commit your changes, and submit a pull request that passes the automated fpb-lint checks.

The free-programming-books repository maintained by the EbookFoundation is a community-curated collection of freely available learning resources. Understanding how to contribute to the free-programming-books repository ensures your submissions meet quality standards and merge efficiently into the curated lists.

Understanding the Contribution Workflow

Review the Guidelines

Before making any changes, read docs/CONTRIBUTING.md thoroughly. This file defines acceptable content (truly free resources with no mandatory registration), formatting specifications, and licensing requirements. For first-time contributors, docs/HOWTO.md provides quick-start guidance and links to GitHub tutorials.

Fork and Clone the Repository

Create your own copy of the repository on GitHub, then clone it locally to work on your changes:

git clone https://github.com/<your-username>/free-programming-books.git
cd free-programming-books
git checkout -b add-new-resource

Edit the Resource Lists

Navigate to the appropriate directory—books/, courses/, casts/, or more/—and locate the language-specific Markdown file (e.g., books/free-programming-books-en.md). Add your entry in strict alphabetical order, following the exact Markdown syntax requirements specified in the contribution guidelines.

Submit Your Pull Request

Commit your changes with a descriptive message, push to your fork, and open a pull request against the main branch of EbookFoundation/free-programming-books:

git add books/free-programming-books-en.md
git commit -m "Add <book-title> to Python books list"
git push origin add-new-resource

Repository Structure and Key Files

Understanding the repository layout helps you navigate to the correct location for your contribution:

File/Directory	Purpose
docs/CONTRIBUTING.md	Comprehensive contribution guidelines, formatting rules, and licensing requirements
docs/HOWTO.md	Quick-start guide for first-time contributors with GitHub tutorials
books/	Markdown files listing free programming books organized by language
courses/	Free online courses organized by programming language
casts/	Podcasts and screencasts
more/	Additional resources like interactive tutorials and problem sets
.github/workflows/fpb-lint.yml	GitHub Actions workflow that validates contributions automatically

Step-by-Step Contribution Tutorial

Here is a complete workflow for adding a new Python book to the repository:

# 1. Fork the repository via GitHub UI, then clone your fork

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

# 2. Create a feature branch

git checkout -b add-python-machine-learning-book

# 3. Edit the appropriate file

# Open books/free-programming-books-en.md and add in alphabetical order:

# * [Machine Learning with Python](https://example.com/ml-book) - Author Name (PDF)

# 4. Stage and commit

git add books/free-programming-books-en.md
git commit -m "Add Machine Learning with Python book"

# 5. Push to your fork

git push origin add-python-machine-learning-book

# 6. Open a Pull Request on GitHub comparing your branch to EbookFoundation/main

Once submitted, the GitHub Actions workflow defined in .github/workflows/fpb-lint.yml automatically triggers. The workflow runs fpb-lint (also known as free-programming-books-lint) which performs three critical validations:

1. Alphabetical ordering – verifies entries are sorted correctly within each section
2. Formatting validation – checks spacing between ] and (, and proper use of format tags like (PDF) or (HTML)
3. Link checking – uses awesome_bot to verify URLs are reachable and not returning 404 errors

If the linter reports errors, the PR page displays a red checkmark. Download the error.log artifact from the Actions tab to see specific line numbers and issues. Fix the problems locally, commit, and push to the same branch—the PR updates automatically and the CI re-runs.

Formatting Rules and Quality Standards

To ensure your contribution passes automated checks and manual review, follow these specific requirements from docs/CONTRIBUTING.md:

• Alphabetical order: Insert new entries in the correct alphabetical position within their category
• Link syntax: Use [Title](URL) format with no space between ] and (
• Format annotations: Append format types in parentheses after the author name, e.g., (PDF), (HTML), (EPUB), or (Code samples)
• Author attribution: Include the author or organization name after the link, separated by a dash and spaces: - Author Name
• Free content only: Ensure resources require no mandatory registration, payment, or personal data beyond email (if strictly necessary)
• No file hosting: Do not link to Google Drive, Dropbox, or similar file-sharing services

Summary

• Read the guidelines: Start with docs/CONTRIBUTING.md and docs/HOWTO.md to understand content requirements and formatting rules.
• Fork and branch: Create a feature branch on your fork to isolate changes from the main codebase.
• Edit list files: Add resources to the appropriate Markdown files in books/, courses/, casts/, or more/ directories, maintaining strict alphabetical order.
• Follow formatting rules: Use correct Markdown syntax, include author names and format tags, and ensure no extra spaces in link definitions.
• Submit and iterate: Open a pull request and fix any errors reported by the fpb-lint GitHub Actions workflow until CI passes.

Frequently Asked Questions

What types of resources can I add to the free-programming-books repository?

You can add freely available programming books, online courses, interactive tutorials, podcasts, and screencasts. All resources must be completely free to access without mandatory registration or payment, and they should not be hosted on temporary file-sharing services like Google Drive or Dropbox.

Why did my pull request fail the automated checks?

The GitHub Actions workflow runs fpb-lint to enforce quality standards. Common failures include incorrect alphabetical ordering of entries, improper spacing in Markdown links (there must be no space between ] and (), missing format tags like (PDF), or broken URLs detected by awesome_bot. Check the error.log artifact in the Actions tab for specific line numbers.

Do I need to know Git to contribute to free-programming-books?

While you can make minor edits directly through GitHub’s web interface, using Git locally provides a better workflow for larger changes. The repository requires you to fork the project, create a feature branch, and submit a pull request—all standard Git operations. If you are new to Git, refer to docs/HOWTO.md for beginner-friendly tutorials.

How do I format a book entry correctly?

Each entry must follow this pattern: * [Title](URL) - Author Name (Format). Ensure there is no space between the closing bracket and opening parenthesis in the link. Place the entry in alphabetical order within its section, and append the format in parentheses after the author (e.g., (PDF), (HTML), (EPUB)). Refer to docs/CONTRIBUTING.md for complete formatting specifications.

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