Contribution Guidelines for Pull Requests in Free Programming Books

All pull requests must follow strict formatting rules defined in docs/CONTRIBUTING.md, including alphabetized Markdown entries, specific syntax patterns, and passing automated CI checks with fpb-lint and awesome_bot.

The EbookFoundation/free-programming-books repository maintains one of the largest curated collections of free programming resources on GitHub. To keep the lists clean and consistent, contributors must adhere to specific contribution guidelines for pull requests that govern everything from link eligibility to Markdown formatting syntax. The definitive rules live in [docs/CONTRIBUTING.md](https://github.com/EbookFoundation/free-programming-books/blob/main/docs/CONTRIBUTING.md), which prescribes exact formatting standards and automated validation requirements.

Eligibility and Resource Requirements

Free Content Verification

According to lines 16‑20 of docs/CONTRIBUTING.md, you may only add resources that are genuinely free. This excludes materials requiring paid subscriptions, sign‑up‑only access, or proprietary file‑hosting services. You must verify that the content remains accessible without payment barriers before submitting.

Selecting the Correct List

Lines 21‑28 of the guidelines specify six distinct categories. Choose the appropriate Markdown file for your resource type:

• Books
• Courses
• Interactive Tutorials
• Playgrounds
• Podcasts/Screencasts
• Problem Sets

Markdown Formatting Standards

The repository enforces rigid formatting rules documented in lines 89‑108 of docs/CONTRIBUTING.md. All entries must use this exact pattern:

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

Critical spacing rules:

• No spaces between ] and (
• Exactly one space before the dash (-)
• One space before the format in parentheses
• One space before any parenthetical notes

Example: Correctly Formatted Entry

* [The Rust Programming Language](https://doc.rust-lang.org/book/) - Steve Klabnik, Carol Nichols (HTML) (CC BY-NC-SA)

This entry demonstrates proper syntax: immediate parenthesis after the bracket, spaced dash separators, and license tagging following the format.

Special Status Notations

For resources that are incomplete or archived, use the specific emoji notations documented in the guidelines. Lines 56‑60 detail the metadata requirements for publication years and author lists (truncate long lists with "et al.").

* [Future of AI](http://example.com/future-ai.html) - Alex Smith (HTML) *( :construction: in process) *( :card_file_box: archived)*

Alphabetical Ordering Requirements

Lines 86‑92 of docs/CONTRIBUTING.md mandate that entries within each section must be sorted alphabetically using case‑insensitive comparison. If two items share a prefix, compare subsequent characters to determine order. The CI linter validates this automatically, and PRs will fail checks if entries are misplaced.

Link Hygiene and Metadata Standards

URL Formatting

Lines 40‑46 specify strict link hygiene rules:

• Prefer https over http when available
• Strip trailing slashes from root domains (http://example.com not http://example.com/)
• Use the shortest, most authoritative URL
• Never use URL shorteners

License and Attribution

According to lines 44‑57 and 56‑60, you must include:

• Author(s): List primary authors, using "et al." for lengthy contributor lists
• Publication year: Required for older books
• License code: If the resource carries a free/open license, append the short code in parentheses after the format (e.g., (CC BY-SA))

Automated CI Checks and Validation

The repository runs mandatory automated checks on every PR. Lines 2‑7 of the Automation section in docs/CONTRIBUTING.md describe the GitHub Actions workflow defined in .github/workflows/fpb-lint.yml. This workflow executes:

• fpb‑lint: Validates Markdown formatting, alphabetical ordering, and syntax compliance
• awesome_bot: Checks URL accessibility and validates link integrity

Your PR must pass both checks or it will be blocked from merging. Address any reported failures by fixing alphabetical ordering errors or correcting malformed URLs.

PR Workflow and Commit Standards

Follow this sequential process to submit a compliant PR:

1. Fork the repository and create a feature branch
2. Edit the appropriate .md list file using the formatting standards above
3. Commit with atomic, descriptive messages (one logical addition per commit). As noted on line 55 of docs/CONTRIBUTING.md, maintainers prefer atomic commits and will handle squashing if necessary
4. Open a PR against the main branch
5. Document eligibility: Lines 37‑38 require you to explain why the resource is free, cite the license source, and note edge cases (e.g., "requires email verification but remains free")
6. Resolve CI failures: Fix any alphabetical ordering or URL validation errors reported by fpb-lint or awesome_bot

PR Description Template

Use this structure to satisfy documentation requirements:

### Summary

Add "The Rust Programming Language" (HTML) – free official documentation.

### Why this is free

The book is published under the CC BY‑NC‑SA license by the Rust project and is available on the official Rust website without any registration.

### License verification

License noted on the "Legal" page of the Rust docs: https://doc.rust-lang.org/book/license.html

Summary

• Resource eligibility: Only free, accessible resources without paywalls or mandatory sign‑ups (lines 16‑20 of docs/CONTRIBUTING.md)
• Exact formatting: Use * [Title](URL) - Author (Format) (License) with strict spacing rules (lines 89‑108)
• Alphabetical order: Sort entries case‑insensitively within sections (lines 86‑92)
• Link standards: Use HTTPS, remove trailing slashes on root domains, avoid URL shorteners (lines 40‑46)
• Metadata required: Include authors, publication years for older works, and license codes in parentheses (lines 56‑60)
• Automated validation: All PRs must pass fpb‑lint and awesome_bot checks defined in .github/workflows/fpb-lint.yml
• Documentation: Explain freeness and license sources in the PR description (lines 37‑38)

Frequently Asked Questions

What happens if my PR fails the automated checks?

The CI pipeline will block merging until you resolve the issues. Check the GitHub Actions logs for specific errors from fpb‑lint (formatting or alphabetical ordering) or awesome_bot (broken or redirected URLs). Fix the identified files, commit the changes, and push to your branch to retrigger validation.

Can I submit multiple resources in a single PR?

While the guidelines prefer atomic commits (line 55 of docs/CONTRIBUTING.md), you may submit multiple resources if they follow the same formatting rules. However, each resource must be alphabetized correctly within its section, and the PR description must justify the freeness of every added link.

How do I indicate that a resource is incomplete or archived?

Append the specific emoji notations to your entry: use :construction: for in‑process resources and :card_file_box: for archived materials. Place these inside parentheses with asterisks, like *( :construction: in process)*, as shown in the metadata guidelines (lines 56‑60).

Where can I find the full list of supported license codes?

The supported short license codes are documented in the "Free Licenses" section of docs/CONTRIBUTING.md (lines 44‑57). Common examples include (CC BY), (CC BY-SA), (CC BY-NC-SA), and (MIT). Always verify the exact license from the resource's official documentation before tagging.

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