Contributing

Contributions from everyone are welcomed. To keep the roadmap practical, accessible, and high quality, the following guidelines should be followed:

1. Prioritize Beginner-Friendliness

Resources and explanations understandable for beginners should be added.
Advanced or specialized topics are welcomed and their inclusion can enrich the roadmap, but they should be explicitly labeled as advanced so beginners are not overwhelmed when choosing resources.

Free and open resources are preferred to maximize accessibility.
Paid resources may be included only if they clearly offer more value than existing free options; low-quality paid/free content should not be promoted.
The list should not be spammed with every publication from the same author or creator solely due to their reputation or personal preference. Each resource should be added for a clear reason, with usefulness especially for beginners prioritized.
Resources should be up-to-date, reliable, and organized under relevant headings.

Clear and direct language should be used. Unnecessary jargon should be avoided. If technical terms are used, simple explanations should be added.
Bullet points and lists should be used for readability and structure.

Contributions should match the topics and structure of the roadmap.
Areas where contributors have experience or genuine interest should be focused on.
If a new topic is thought to make the roadmap more complete, it may be suggested. New topics should be proposed thoughtfully, considering their usefulness and relevance for other learners.
Connections between topics on the map are listed in site/map.json under links as ["Topic", "Other topic", "why they are related"], using the names shown on the map. Connect topics that a learner should study together or that depend on each other, and keep the reason to one short sentence. Tests fail if a name is misspelled, a pair is listed twice or a topic has no connection.

The interactive roadmap reads README.md directly; there is no other copy of the content. Most contributions need no change outside the README.

Topics come from heading depth: ## is a group, ### a main topic, #### and deeper are subtopics. The emojis in headings (✳️ 🔵 🔶 🔸) are decoration only. Renaming a heading changes its link (#/topic-name).
Resources are list items in the form - [📘👶💎 Title](https://url), optionally followed by a dash and a short note. Symbols: 📘 book, 🎞️ video, 📝 article, 🔗 link, 🎧 audio, 👶 beginner, 💎 essential. python3 .github/scripts/check_readme.py checks the format and duplicates.
The map (site/map.json) draws only the main topics. Each label on it opens the README heading with the same name. If the wording differs, or the label has no section of its own, add "Label": ["README heading"] to readme in site/map.json. A new main topic needs a README section and a box in site/map.json (and at least one entry in links), unless it should stay off the map: then list its title or group in offMap. CI warns about main topics that are neither.
Preview and test locally: python3 -m http.server 8765 from the repository root, then open /site/; node --test site/parser.test.mjs runs the checks CI runs.

The roadmap image is versioned as vMAJOR.MINOR.PATCH, starting from v2.0.0.

No new version for changes that do not change the roadmap map, such as new learning resources, descriptions or documentation.
Patch (v2.0.0 → v2.0.1) is automatic: when a change merged into master changes the rendered map, CI publishes the next patch release with the PDF and PNG attached.
Minor (v2.0.234 → v2.1.0) and major (v2.43.57 → v3.0.0) are decided by the maintainer: run the Roadmap explorer workflow from the Actions tab on master and choose minor or major.

Releases should not be created by hand; the workflow renders the files and records the map fingerprint that later builds compare against.