# 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.