mirror of
https://github.com/m3y54m/Embedded-Engineering-Roadmap.git
synced 2026-10-10 16:28:24 +03:00
Meysam Parvizi
4c52895477
Connections come from the links list in map.json instead of only from shared or mentioned resources. Curated ones are solid lines with a reason in the details panel; the text-based ones stay as faint dashed evidence. Tests check names, duplicates and that every technical topic is connected.
44 lines
3.0 KiB
Markdown
44 lines
3.0 KiB
Markdown
|
|
# 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.
|
|
|
|
## 2. Resource Selection Policy
|
|
|
|
- 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.
|
|
|
|
## 3. Clarity & Structure
|
|
|
|
- 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.
|
|
|
|
## 4. Technical Accuracy
|
|
|
|
- The correctness and relevance of all information and links should be verified.
|
|
- If uncertainty exists, feedback should be requested in the pull request.
|
|
|
|
## 5. Roadmap Alignment
|
|
|
|
- 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.
|
|
|
|
## 6. Versioning and Releases
|
|
|
|
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.
|