WAIT — Mixed signals — read the receipts

• Last commit 1d ago
• 79+ active contributors
• Distributed ownership (top contributor 7% of recent commits)
• CC-BY-4.0 licensed
• CI configured
• ⚠ Non-standard license (CC-BY-4.0) — review terms
• ⚠ No test directory detected
• ⚠ Scorecard: default branch unprotected (0/10)

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests + OpenSSF Scorecard}

A crowdsourced, multilingual catalog of freely available programming books maintained as Markdown files across 50+ language translations in the books/ directory. The project generates both static HTML sites and powers a dynamic search interface (ebookfoundation.github.io/free-programming-books-search/) for discovering free learning resources by language, topic, and author. Flat structure: 50+ Markdown files in books/ directory (one per language: free-programming-books-en.md, free-programming-books-fr.md, etc.), shared linting/validation via Python scripts in the repo root, GitHub Actions workflows in .github/workflows/ orchestrating link validation and PR checks, and Jekyll config (_config.yml) publishing to GitHub Pages. No monorepo; each language file is independent but follows identical Markdown schema.

Programmers and students seeking free learning materials in their native language, plus maintainers and contributors (via Pull Requests) who curate, validate, and translate book listings. Teachers and educational organizations building curricula also use this as a source list.

Highly mature and production-ready: the repo is one of GitHub's most-starred projects with extensive CI/CD workflows (check-urls.yml, fpb-lint.yml, rtl-ltr-linter.yml) validating every contribution, comprehensive GitHub Actions automation for link checking and PR management, and multi-year track record of sustained community contributions. The project has proven stability in real-world use across millions of users.

Standard open source risks apply.

Active development: Hacktoberfest 2025 integration visible in badges, continuous URL validation via check-urls.yml workflow, automated RTL/LTR language linting (rtl-ltr-linter.yml), stale PR/issue management (stale.yml), and conflict detection for simultaneous edits (detect-conflicting-prs.yml). Community is actively submitting book additions and translations.

git clone https://github.com/EbookFoundation/free-programming-books.git
cd free-programming-books
# No install needed — pure Markdown repo. To validate locally:
pip install -r requirements.txt  # (inferred; check root for requirements.txt)
python fpb_lint.py  # Run linter on Markdown files

Daily commands: No local server runtime — this is a content repository. To preview HTML locally: jekyll serve (if Jekyll installed). To validate Markdown: python fpb_lint.py (if linting script exists in root). To test URL integrity: GitHub Actions runs check-urls.yml automatically on PRs.

• books/free-programming-books-en.md: Primary English book catalog; largest and most-referenced translation; template for all other language files
• books/free-programming-books-langs.md: Index of all 50+ languages; used to generate language switcher on website and to validate that all language files are registered
• .github/workflows/check-urls.yml: Validates every book link in PRs to prevent dead links from being merged; critical for content quality
• .github/workflows/fpb-lint.yml: Enforces Markdown schema and formatting rules (list structure, link syntax, metadata) across all language files
• .github/workflows/rtl-ltr-linter.yml: Ensures proper Unicode directionality for right-to-left languages (Arabic, Hebrew, Persian); prevents UI corruption
• .github/PULL_REQUEST_TEMPLATE.md: Standardizes PR descriptions; helps contributors understand contribution guidelines and quality expectations
• _config.yml: Jekyll configuration for GitHub Pages site generation; controls theme, plugins, and site metadata

1. Add/update books: edit language-specific file in books/free-programming-books-{LANG}.md (e.g., books/free-programming-books-en.md for English). 2. Add new language: create new Markdown file following naming convention books/free-programming-books-{LANG_CODE}.md and reference it in books/free-programming-books-langs.md. 3. Change validation rules: modify Python linting scripts in repo root (likely fpb_lint.py or similar). 4. Update workflows: edit .github/workflows/*.yml files for CI/CD behavior.

1. Language code format matters: filenames must use exact language codes (e.g., pt_BR for Brazilian Portuguese, pt_PT for European Portuguese); typos break the build. 2. Markdown link syntax strict: links must follow exact format [Title](URL) for automated validators to work; minor deviations cause linting failures. 3. URL validation timeout: check-urls.yml may timeout or rate-limit when validating thousands of links; PRs with many new links may fail checks spuriously. 4. No local dependencies: repo has no requirements.txt visible; linting scripts may be embedded in GitHub Actions or external tools, making local validation difficult without documentation.

• Markdown linting & schema validation — This repo enforces consistent Markdown structure across 50+ files via fpb-lint.yml; understanding linting rules is essential to avoid PR rejection when adding books
• URL health checking in CI/CD — check-urls.yml validates every link in the catalog automatically; contributors must understand link validation failures and how to respond with mirror URLs or removals
• Bidirectional text (BiDi) and Unicode directionality — rtl-ltr-linter.yml enforces proper text direction for RTL languages (Arabic, Hebrew, Persian, Urdu); without this, book titles in these languages render incorrectly on the website
• Static site generation with Jekyll — This project uses Jekyll to convert Markdown files into a GitHub Pages website; understanding Jekyll config (_config.yml) is needed to modify site layout or metadata
• GitHub Actions workflow automation — The .github/workflows/ directory contains 8+ YAML workflows orchestrating linting, URL checks, and PR management; modifying validation rules requires editing these workflows
• Collaborative content curation at scale — This repo demonstrates patterns for managing thousands of community PRs across 50+ language variants without centralized editorial control; useful for understanding open content governance
• Localization and internationalization (i18n) — The 50+ language files represent a massive i18n challenge; contributors must understand how to add new languages, translate metadata, and handle language-specific formatting conventions

• awesome-python/awesome-python — Sibling project in 'awesome' ecosystem; curates free Python learning resources in a single language; demonstrates alternative curation approach for comparison
• awesome/awesome — Meta-repository linking thousands of curated 'awesome' lists; free-programming-books is listed here; shows where this project fits in the broader discovery landscape
• EbookFoundation/free-programming-books-search — Companion repository providing the dynamic search interface (ebookfoundation.github.io/free-programming-books-search/) that powers live discovery of books from this data source
• github/gitignore — Similar large multilingual community-curated content project; demonstrates scaling patterns for high-volume community contributions and language variants
• sindresorhus/awesome — Original awesome list inspiration and format standard; free-programming-books follows this curation philosophy and styling conventions

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Create a linting rule to validate markdown link syntax across all language files

The repo contains 40+ markdown files in books/ and casts/ directories across many languages. While fpb-lint.yml workflow exists, there's no specific validation for consistent markdown link formatting (e.g., title vs [title] (url)). Add a dedicated linter script to catch spacing issues, missing brackets, and malformed URLs before they're merged, reducing manual review burden.

• [ ] Create scripts/validate-markdown-links.js to parse and validate markdown link syntax
• [ ] Add validation rules for bracket spacing, URL format, and link structure
• [ ] Integrate into .github/workflows/fpb-lint.yml as a new job step
• [ ] Document expected markdown format in CONTRIBUTING.md (if it exists)
• [ ] Test against books/free-programming-books-en.md and books/free-programming-books-es.md

Add language-specific contributor guides for non-English book files

The repo has 40+ language variants (ar, de, fr, ja, zh, etc.) but likely only has English documentation. Create localized CONTRIBUTING guides for major language communities (at least 5-10 languages) so non-English speakers understand contribution standards, quality expectations, and how to add books in their language.

• [ ] Create docs/CONTRIBUTING-[lang].md for top 10 languages by file count (de, es, fr, ja, pt_BR, ru, zh, etc.)
• [ ] Include language-specific book sources, quality standards, and submission examples
• [ ] Link to these guides from main CONTRIBUTING.md with language selectors
• [ ] Use existing book entries in books/free-programming-books-[lang].md as reference examples
• [ ] Have native speakers review for clarity and cultural appropriateness

Create a data validation schema and migration script for markdown frontmatter standardization

With 40+ markdown files across languages, there's risk of inconsistent metadata, section headers, and formatting. Create a JSON schema defining valid file structure (required sections, metadata format) and a migration script that validates all files against it. This prevents silent formatting divergence as contributors add books.

• [ ] Define schema/books-schema.json with required sections, heading levels, and metadata fields based on inspection of books/free-programming-books-en.md
• [ ] Create scripts/validate-schema.js to check all files in books/ and casts/ directories
• [ ] Add schema validation to .github/workflows/fpb-lint.yml
• [ ] Generate a report of files that don't conform (if any) for contributor guidance
• [ ] Document schema requirements in a SCHEMA.md for future maintainers

• Add missing books to a high-traffic language (e.g., free-programming-books-en.md): identify popular free books not yet listed, verify their URLs are live and freely accessible, and submit a PR with properly formatted entries following the existing Markdown schema
• Translate category descriptions into an underrepresented language: many language files have English-only section headers; pick a language with few translations (check books/ for shorter files) and translate category names and descriptions while preserving URLs
• Fix dead links identified by check-urls.yml: search past PR comments for links flagged as broken (HTTP 404, timeouts, redirects); replace with working mirrors or updated URLs, or remove entries if no alternative exists

This repository is primarily a curated list of free programming books with minimal code execution risk. The main security concerns are related to external resource references (deprecated CDN), GitHub Actions workflow practices, and missing security documentation. No hardcoded secrets, SQL injection risks, or XSS vulnerabilities were detected in the file structure. The codebase appears to be a documentation-focused project with good security practices overall, but should strengthen its CI/CD and external dependency management. Recommended actions: (1) Replace deprecated CDN URLs, (2) Create SECURITY.md with vulnerability reporting guidelines, (3) Audit and harden GitHub Actions workflows, (4) Implement strict dependency review practices.

• Medium · Insecure CDN Resource for Badge — README.md - Awesome badge SVG reference. The README uses a rawgit.com CDN URL (cdn.rawgit.com) to load the Awesome badge SVG. The rawgit.com service is deprecated and no longer maintained, which could pose security risks if the domain is compromised or repurposed. Fix: Replace the rawgit.com CDN URL with a secure alternative such as jsdelivr.net, unpkg.com, or host the badge locally. Example: 'https://cdn.jsdelivr.net/gh/sindresorhus/awesome@d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg'
• Low · GitHub Actions Workflow Security — .github/workflows/ directory. Multiple GitHub Actions workflows are present (.github/workflows/) but cannot be fully analyzed from the file listing. Potential risks include: use of third-party actions without version pinning, secrets exposure in logs, and insufficient access controls. Fix: Review all workflow files to ensure: (1) Third-party actions are pinned to specific commit SHAs, not branches; (2) Secrets are never logged; (3) Workflow permissions follow principle of least privilege; (4) Branch protection rules are enforced; (5) Code review is required for changes to workflows
• Low · Missing Security Policy — Repository root. No SECURITY.md file is present in the root directory. This could make it difficult for security researchers to responsibly report vulnerabilities. Fix: Create a SECURITY.md file in the root directory with responsible disclosure guidelines, including how to report security vulnerabilities privately and what the expected response timeframe is.
• Low · Dependabot Configuration Present — .github/dependabot.yml. While Dependabot is configured (.github/dependabot.yml), automatic dependency updates could introduce untested code. Without sufficient CI/CD testing, this could be a risk. Fix: Ensure comprehensive automated testing is in place for all dependencies. Require manual review and approval of Dependabot pull requests before merging, especially for major version updates.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/EbookFoundation/free-programming-books shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live EbookFoundation/free-programming-books repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/EbookFoundation/free-programming-books.

What it runs against: a local clone of EbookFoundation/free-programming-books — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in EbookFoundation/free-programming-books | Confirms the artifact applies here, not a fork | | 2 | License is still CC-BY-4.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of EbookFoundation/free-programming-books. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/EbookFoundation/free-programming-books.git
#   cd free-programming-books
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of EbookFoundation/free-programming-books and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "EbookFoundation/free-programming-books(\\.git)?\\b" \\
  && ok "origin remote is EbookFoundation/free-programming-books" \\
  || miss "origin remote is not EbookFoundation/free-programming-books (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(CC-BY-4\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"CC-BY-4\\.0\"" package.json 2>/dev/null) \\
  && ok "license is CC-BY-4.0" \\
  || miss "license drift — was CC-BY-4.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/EbookFoundation/free-programming-books"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.