|
| 1 | +# Contributing to Git Chronicles |
| 2 | + |
| 3 | +First off, thanks for taking the time to contribute! This project started as a learning resource for friends and colleagues, and community contributions help make it better for everyone. |
| 4 | + |
| 5 | +## Code of Conduct |
| 6 | + |
| 7 | +This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to daihyxsk+coc.github@pm.me. |
| 8 | + |
| 9 | +## How can I contribute? |
| 10 | + |
| 11 | +### Reporting bugs |
| 12 | + |
| 13 | +Use the [Bug Report](https://github.com/Dxsk/git-chronicles/issues/new?template=bug_report.yml) issue template. Include: |
| 14 | +- The affected page or quest |
| 15 | +- The language (FR/EN) |
| 16 | +- Steps to reproduce |
| 17 | +- Screenshots if relevant |
| 18 | + |
| 19 | +### Suggesting improvements |
| 20 | + |
| 21 | +Use the [Content Improvement](https://github.com/Dxsk/git-chronicles/issues/new?template=content_improvement.yml) or [Feature Request](https://github.com/Dxsk/git-chronicles/issues/new?template=feature_request.yml) issue templates. |
| 22 | + |
| 23 | +### Submitting changes |
| 24 | + |
| 25 | +1. **Open an issue first** to discuss the change you'd like to make. |
| 26 | +2. Fork the repository and create a branch from `main`. |
| 27 | +3. Make your changes. |
| 28 | +4. Run the checks before submitting: |
| 29 | + ```bash |
| 30 | + npm run check |
| 31 | + ``` |
| 32 | + This runs i18n parity checks, the build, link checking, and accessibility checks. |
| 33 | +5. Open a Pull Request referencing the related issue. |
| 34 | + |
| 35 | +## Development setup |
| 36 | + |
| 37 | +```bash |
| 38 | +git clone https://github.com/<your-fork>/git-chronicles.git |
| 39 | +cd git-chronicles |
| 40 | +npm install |
| 41 | +npm run dev # Local server with hot reload |
| 42 | +``` |
| 43 | + |
| 44 | +Requires **Node.js 18+**. |
| 45 | + |
| 46 | +## Project structure |
| 47 | + |
| 48 | +``` |
| 49 | +src/ |
| 50 | + fr/quetes/ # French quest content (Nunjucks templates) |
| 51 | + en/quests/ # English quest content |
| 52 | + assets/ # CSS, JS (vanilla, no dependencies) |
| 53 | +exercises/ |
| 54 | + */verifier.sh # Bash verification scripts |
| 55 | + */verifier.ps1 # PowerShell verification scripts |
| 56 | +themes/fantasy/ # Theme messages (i18n) |
| 57 | +``` |
| 58 | + |
| 59 | +## Content guidelines |
| 60 | + |
| 61 | +### Bilingual content |
| 62 | + |
| 63 | +The course is bilingual (FR/EN). If you modify quest content in one language, the corresponding content in the other language should also be updated. The `npm run check:i18n` script verifies parity between both languages. |
| 64 | + |
| 65 | +### Writing style |
| 66 | + |
| 67 | +- Keep explanations clear and beginner-friendly. |
| 68 | +- Use the fantasy narrative tone (guilds, quests, scrolls) to stay consistent with the rest of the course. |
| 69 | +- Explain the *why*, not just the *how*. |
| 70 | +- Include practical examples whenever possible. |
| 71 | + |
| 72 | +### Verification scripts |
| 73 | + |
| 74 | +Each quest has verification scripts in both Bash (`verifier.sh`) and PowerShell (`verifier.ps1`). If you add or modify a quest, update both scripts. They support `--lang fr` and `--lang en` flags. |
| 75 | + |
| 76 | +## Types of welcome contributions |
| 77 | + |
| 78 | +- Fixing typos or unclear explanations |
| 79 | +- Improving accessibility |
| 80 | +- Adding or improving translations |
| 81 | +- Writing new quests or bonus quests |
| 82 | +- Improving verification scripts |
| 83 | +- Fixing CSS/JS issues |
| 84 | + |
| 85 | +## Licenses |
| 86 | + |
| 87 | +By contributing, you agree that your contributions will be licensed under: |
| 88 | +- **[MIT](LICENSE-MIT)** for code (scripts, CSS, JS, templates) |
| 89 | +- **[CC BY-SA 4.0](LICENSE-CC-BY-SA)** for content (quest texts, cheatsheets, narratives) |
0 commit comments