How to Update or Correct Information for an Existing Resource Entry in Free Programming Books

To update an existing resource in the Free Programming Books repository, edit the relevant Markdown file in books/, courses/, or more/ directories, ensure the entry follows the * [Title](URL) - Author (Format) (License) format, and submit a pull request that passes the automated linting workflow.

The EbookFoundation/free-programming-books repository organizes thousands of learning resources as Markdown list items across language-specific files. When you need to update or correct information for an existing resource entry—whether fixing a broken URL, adding a missing license, or updating metadata—you must follow the project's specific contribution conventions to ensure your changes pass automated validation.

Locating the Correct File for Your Resource Update

Each resource category resides in a dedicated directory: books/ for written materials, courses/ for video courses, and more/ for additional resources. Within these directories, files are split by language using the naming pattern free-programming-books-{language-code}.md.

To find the correct file:

• Identify the language of the existing entry (e.g., English, Russian, Spanish)
• Navigate to the appropriate directory (books/, courses/, etc.)
• Open the file matching the language code (e.g., books/free-programming-books-en.md for English books)

Editing the Markdown Entry to Correct Resource Information

Once you locate the entry, modify the single Markdown line while preserving the repository's strict formatting rules documented in docs/CONTRIBUTING.md.

Required Formatting Syntax

Maintain the standard list item structure:

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

• Title: The resource name in square brackets
• URL: The link in parentheses, using HTTPS where possible
• Author: Preceded by a dash and space (-)
• Format: Optional but recommended (HTML, PDF, GitHub, etc.)
• License: Optional (CC BY, MIT, etc.)
• Notes: Optional italicized remarks in asterisks

Maintaining Alphabetical Order

If your correction changes the title, you must reposition the entry to maintain alphabetical order within its section. The linter and CI workflow enforce this ordering.

URL and Metadata Standards

When correcting URLs or metadata:

• Replace HTTP with HTTPS where available
• Remove tracking parameters (UTM codes, referral IDs)
• Avoid URL shorteners (bit.ly, tinyurl, etc.)
• Update or add license information if known
• Mark archived resources with *(archived)* or in-process courses with *(in process)*

Validating Your Changes with the Local Linter

Before submitting, verify your edits using the free-programming-books-lint npm package to catch formatting errors locally.

Install the linter globally:

npm install -g free-programming-books-lint

Validate a specific file:

fpb-lint books/free-programming-books-en.md

The linter checks for alphabetical ordering, proper spacing, URL validity, and formatting consistency. Fixing errors locally prevents CI failures and speeds up the review process.

Submitting Your Resource Correction via Pull Request

After validating your changes, submit them through the standard GitHub pull request workflow.

Commit Message Conventions

Write clear, descriptive commit messages and PR titles:

• Good: "Fix HTTPS URL for Learn Python the Hard Way"
• Good: "Add missing CC BY-SA license to Eloquent JavaScript entry"
• Avoid: "Update books" or "Fix stuff"

Automated CI Validation

When you open a pull request, the repository's GitHub Actions workflow defined in .github/workflows/fpb-lint.yml automatically executes. This workflow runs free-programming-books-lint against the modified files to enforce formatting rules.

If the workflow reports errors:

1. Check the Actions tab for specific file and line references
2. Correct the formatting issues locally
3. Commit and push the fixes to your PR branch
4. The workflow will re-run automatically

Once the CI passes and a maintainer approves the changes, your correction merges into the main branch and updates the public resource list.

Summary

• Locate the correct language-specific Markdown file in books/, courses/, or more/ directories
• Edit the entry using the standard * [Title](URL) - Author (Format) (License) syntax while maintaining alphabetical order
• Validate changes locally using npm install -g free-programming-books-lint and fpb-lint <filename>
• Submit a pull request with a descriptive title; ensure it passes the automated linting workflow defined in .github/workflows/fpb-lint.yml

Frequently Asked Questions

What file format should I use when updating a resource entry?

The Free Programming Books repository uses Markdown (.md) files exclusively. Each resource appears as a single bullet point line within a list, formatted as * [Title](URL) - Author (Format) (License). Do not use HTML tags or reStructuredText; the automated linter in .github/workflows/fpb-lint.yml validates strict Markdown compliance.

How do I fix a broken URL in the Free Programming Books repository?

To fix a broken URL, locate the entry in the appropriate language file (e.g., books/free-programming-books-en.md), update the link within the parentheses to a working HTTPS URL, and remove any tracking parameters. Verify the fix by running fpb-lint <filename> locally, then submit a pull request with a title like "Fix URL for [Resource Name]".

Do I need to install the linter locally before submitting a correction?

Local installation is optional but strongly recommended. While the CI workflow in .github/workflows/fpb-lint.yml will catch errors after you submit a pull request, installing free-programming-books-lint via npm install -g free-programming-books-lint allows you to identify and fix formatting issues immediately, reducing review cycles and preventing CI failures.

What happens if my pull request fails the automated linting check?

If the GitHub Actions workflow defined in .github/workflows/fpb-lint.yml reports failures, your pull request will display a red checkmark. You must click the Actions tab to view specific error messages (typically regarding alphabetical ordering, URL formatting, or spacing), correct the issues in your branch, and push a new commit. The workflow automatically re-runs on each update until all checks pass.

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