This page documents the detailed standards and rules that all contributions must follow when adding resources to the Free Programming Books repository. These guidelines ensure consistency across 40+ language editions and thousands of resources.
For step-by-step instructions on making your first contribution, see Getting Started with Contributions. For community behavior expectations, see Community Code of Conduct.
The contribution guidelines are maintained in docs/CONTRIBUTING.md with translations available in 40+ languages (see docs/README.md5-149). These rules define:
All contributions are validated by GitHub Actions workflows (see Quality Assurance and Automation) before human review.
The repository accepts six distinct resource types, each with specific inclusion criteria:
Category Decision Rules
Sources: docs/CONTRIBUTING-ta.md21-28 docs/CONTRIBUTING-ml.md19-26 docs/CONTRIBUTING-hi.md18-25
| Resource Type | Primary Indicator | File Location | Examples |
|---|---|---|---|
| Books | Self-contained learning material with structure | books/free-programming-books*.md | PDF, HTML, ePub, gitbook.io sites, Git repos |
| Courses | Structured curriculum with lectures/exercises | courses/free-courses*.md | MIT OCW courses, Coursera, EdX offerings |
| Interactive Tutorials | Code evaluation in browser | more/free-programming-interactive-tutorials*.md | Try Haskell, Try Git |
| Playgrounds | Online coding environment | more/free-programming-playgrounds.md | CodePen, JSFiddle, Repl.it |
| Podcasts/Screencasts | Audio/video content | casts/free-podcasts-screencasts*.md | Programming podcasts, tutorial videos |
| Problem Sets | Coding challenges platform | more/problem-sets-competitive-programming.md | LeetCode, Codeforces, HackerRank |
The following are not accepted:
Sources: docs/CONTRIBUTING-ta.md260-271 docs/CONTRIBUTING-ml.md260-272
Title Rules:
<FileRef file-url="https://github.com/EbookFoundation/free-programming-books/blob/6a7d2f47/Book Title (1970)" undefined file-path="Book Title (1970)">Hii</FileRef> docs/CONTRIBUTING-ta.md125-130| Rule | Correct | Incorrect |
|---|---|---|
| HTTPS preferred | https://example.com | http://example.com (if HTTPS available) |
| No trailing slash (root) | https://example.com | https://example.com/ |
| Shortest path | https://example.com/dir/ | https://example.com/dir/index.html |
| Current over versioned | https://example.com/book/current/ | https://example.com/book/v1.0.0/ |
| No URL shorteners | https://example.com/resource | https://bit.ly/xxxxx |
| No tracking codes | https://example.com/page | https://example.com/page?utm_source=... |
| Escape international | Properly encoded | Raw Unicode in URL |
SSL Certificate Issues:
http version if available docs/CONTRIBUTING-ta.md47-50http but accessible via exception: Leave as https docs/CONTRIBUTING-ta.md48-50Rejected Hosting Platforms:
Sources: docs/CONTRIBUTING-ta.md38 docs/CONTRIBUTING-ml.md37
Author Formatting Rules:
John Doe, Jane Roe docs/CONTRIBUTING-ta.md230trl.: - Example: - John Doe, trl.: Mike The Translator docs/CONTRIBUTING-ta.md223-228et al. for long author lists docs/CONTRIBUTING-ta.md231Compiled from StackOverflow documentation docs/CONTRIBUTING-ta.md233Sources: docs/CONTRIBUTING-ta.md220-234 docs/CONTRIBUTING-ml.md218-238
All resource lists use Markdown (.md) files with strict structural requirements:
Spacing Rules:
| Location | Empty Lines Required | Rule Reference |
|---|---|---|
| After last link before new section | 2 | docs/CONTRIBUTING-ta.md71 |
| After heading before first link | 1 | docs/CONTRIBUTING-ta.md72 |
| Between two links | 0 | docs/CONTRIBUTING-ta.md73 |
End of .md file | 1 | docs/CONTRIBUTING-ta.md74 |
Example:
Sources: docs/CONTRIBUTING-ta.md64-87 docs/CONTRIBUTING-ml.md64-87
Syntax Rules:
| Element | Correct | Incorrect | Rule |
|---|---|---|---|
| Link brackets | ](http | ] (http | No space between ] and ( docs/CONTRIBUTING-ta.md89-94 |
| Author separator | - | - or - | Space-dash-space docs/CONTRIBUTING-ta.md96-101 |
| Format separator | (PDF) | (PDF) | Space before format docs/CONTRIBUTING-ta.md103-108 |
| Author placement | - Author (PDF) | - (PDF) Author | Author before format docs/CONTRIBUTING-ta.md110-115 |
Multiple Formats:
When a single resource provides multiple formats:
Rationale: Each link adds maintenance burden. Prefer single link with format list. docs/CONTRIBUTING-ta.md117-123
For incomplete works still under development:
Sources: docs/CONTRIBUTING-ta.md132-136
For resources restored via Internet Archive Wayback Machine:
Use recent, complete versions when available. docs/CONTRIBUTING-ta.md138-142
Supported License Codes (without version numbers):
| Code | Full Name |
|---|---|
CC BY | Creative Commons Attribution |
CC BY-NC | Creative Commons Non-Commercial |
CC BY-SA | Creative Commons Share-Alike |
CC BY-NC-SA | Creative Commons Non-Commercial, Share-Alike |
CC BY-ND | Creative Commons No-Derivatives |
CC BY-NC-ND | Creative Commons Non-Commercial, No-Derivatives |
GFDL | GNU Free Documentation License |
Adding License Notation (Step-by-Step):
CC BY-SA 3.0 → CC BY-SA docs/CONTRIBUTING-ta.md167-168Sources: docs/CONTRIBUTING-ta.md144-184 docs/CONTRIBUTING-ml.md144-184
All resource lists must be sorted alphabetically to pass automated validation.
Ordering Rules:
one two comes before onetwo (space creates earlier sort) docs/CONTRIBUTING-ta.md189aa comes before ab docs/CONTRIBUTING-ta.md188Validation:
The fpb-lint workflow validates alphabetical order. If incorrect, the linter error message indicates which lines need swapping. docs/CONTRIBUTING-ta.md191-192
Sources: docs/CONTRIBUTING-ta.md186-192 docs/CONTRIBUTING-ml.md187-193
For courses, the platform is a critical piece of metadata:
Common Platforms:
Rationale: Course platforms have different affordances and access models. Many require accounts but offer free audit access. docs/CONTRIBUTING-ta.md246-248
youtu.be/xxxx format docs/CONTRIBUTING-ta.md249Leanpub hosts books with varying access models:
Note added when registration/email required for free access. docs/CONTRIBUTING-ta.md250-251
If resource requires email address (but not payment):
Sources: docs/CONTRIBUTING-ta.md60 docs/CONTRIBUTING-ml.md59
For right-to-left (RTL) language files (*-ar.md, *-he.md, *-fa.md, *-ur.md), special Unicode markers prevent bidirectional text corruption.
| LTR Content Type | Marker to Add | Placement | Example |
|---|---|---|---|
| LTR Words (e.g., HTML, JavaScript, R) | ‏ | Immediately after each LTR word | <FileRef file-url="https://github.com/EbookFoundation/free-programming-books/blob/6a7d2f47/كتاب في R‏" undefined file-path="كتاب في R‏">Hii</FileRef> |
| LTR Symbols (e.g., C#, C++, .NET) | ‎ | Immediately after each LTR symbol | <FileRef file-url="https://github.com/EbookFoundation/free-programming-books/blob/6a7d2f47/أساسيات C#‎" undefined file-path="أساسيات C#‎">Hii</FileRef> |
Without Markers (Incorrect):
With Markers (Correct):
Symbol Example (Incorrect):
Symbol Example (Correct):
Multiple LTR Elements:
Sources: docs/CONTRIBUTING-ta.md316-362 docs/CONTRIBUTING-ml.md318-362
All contributions are validated by GitHub Actions before merge.
fpb-lint Checks:
| Check | Rule | Error Message Pattern |
|---|---|---|
| Alphabetical order | Resources must be sorted A-Z | "Line X should come before line Y" |
| Link syntax | No space between ] and ( | "Space found between ] and (" |
| Author separator | Must use - (space-dash-space) | "Incorrect author separator" |
| Format placement | Space before format parentheses | "Missing space before format" |
| Empty lines | 0/1/2 lines per rule | "Incorrect number of blank lines" |
| RTL markers | ‏ or ‎ after LTR text in RTL files | "Missing RTL/LTR marker" |
awesome_bot URL Checks:
| Check | Validation |
|---|---|
| HTTP status | Must return 200-399 |
| SSL certificates | Must be valid (or use HTTP) |
| Redirects | Resolved final URL reported |
| Broken links | 404/500 errors flagged |
URL checks run when commit message contains:
Sources: docs/CONTRIBUTING-ta.md302-314 docs/CONTRIBUTING-ml.md300-315
Not Accepted:
Rationale: Content must remain accessible. Six-month removal rule. docs/CONTRIBUTING-ta.md239
When resource exists in multiple locations:
Sometimes difficult to categorize:
Books have:
Courses have:
Not courses: Single lecture, single video, PowerPoint presentation docs/CONTRIBUTING-ta.md294
Sources: docs/CONTRIBUTING-ta.md275-294 docs/CONTRIBUTING-ml.md274-293
Contributing guidelines themselves are translated into 40+ languages. Available translations:
| Language | Files Available |
|---|---|
| English | CONTRIBUTING.md, CODE_OF_CONDUCT.md, HOWTO.md |
| Tamil | CONTRIBUTING-ta.md, CODE_OF_CONDUCT-ta.md, HOWTO-ta.md |
| Malayalam | CONTRIBUTING-ml.md, CODE_OF_CONDUCT-ml.md, HOWTO-ml.md |
| Hindi | CONTRIBUTING-hi.md, CODE_OF_CONDUCT-hi.md, HOWTO-hi.md |
| Vietnamese | CONTRIBUTING-vi.md, CODE_OF_CONDUCT-vi.md, HOWTO-vi.md |
| 40+ more | See docs/README.md5-149 for complete list |
To contribute a new translation:
CONTRIBUTING-{language_code}.mdTranslation note at top of each file: *<FileRef file-url="https://github.com/EbookFoundation/free-programming-books/blob/6a7d2f47/Read this in other languages" undefined file-path="Read this in other languages">Hii</FileRef>* docs/CONTRIBUTING-ta.md1
Sources: docs/README.md1-149 docs/CONTRIBUTING-ta.md1 docs/CONTRIBUTING-ml.md1 docs/CONTRIBUTING-vi.md34
Refresh this wiki