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

> Learn how to contribute to the free-programming-books repository with this guide Fork edit commit and submit a pull request to share your knowledge

- Repository: [Free Ebook Foundation/free-programming-books](https://github.com/EbookFoundation/free-programming-books)
- Tags: how-to-guide
- Published: 2026-02-23

---

**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`](https://github.com/EbookFoundation/free-programming-books/blob/main/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`](https://github.com/EbookFoundation/free-programming-books/blob/main/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`](https://github.com/EbookFoundation/free-programming-books/blob/main/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:

```bash
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`](https://github.com/EbookFoundation/free-programming-books/blob/main/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`:

```bash
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`](https://github.com/EbookFoundation/free-programming-books/blob/main/docs/CONTRIBUTING.md) | Comprehensive contribution guidelines, formatting rules, and licensing requirements |
| [`docs/HOWTO.md`](https://github.com/EbookFoundation/free-programming-books/blob/main/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`](https://github.com/EbookFoundation/free-programming-books/blob/main/.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:

```bash

# 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`](https://github.com/EbookFoundation/free-programming-books/blob/main/.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`](https://github.com/EbookFoundation/free-programming-books/blob/main/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`](https://github.com/EbookFoundation/free-programming-books/blob/main/docs/CONTRIBUTING.md) and [`docs/HOWTO.md`](https://github.com/EbookFoundation/free-programming-books/blob/main/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`](https://github.com/EbookFoundation/free-programming-books/blob/main/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`](https://github.com/EbookFoundation/free-programming-books/blob/main/docs/CONTRIBUTING.md) for complete formatting specifications.