From 5d101327636c25da9ebe6c2ca2ff63da8b92b198 Mon Sep 17 00:00:00 2001
From: Edu <edullerandi@gmail.com>
Date: Sat, 1 Aug 2026 11:44:52 +0200
Subject: [PATCH] feat: add CONTRIBUTING.md and issue templates

---
 .github/ISSUE_TEMPLATE/bug_report.yml      | 47 ++++++++++++++++++++++
 .github/ISSUE_TEMPLATE/feature_request.yml | 27 +++++++++++++
 CONTRIBUTING.md                            | 40 ++++++++++++++++++
 README.md                                  |  4 +-
 4 files changed, 116 insertions(+), 2 deletions(-)
 create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml
 create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml
 create mode 100644 CONTRIBUTING.md

diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
new file mode 100644
index 0000000..ae26f65
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,47 @@
+name: Bug report
+description: Something is not working as expected.
+labels: ["bug"]
+body:
+  - type: dropdown
+    id: platform
+    attributes:
+      label: Platform
+      options:
+        - Linux
+        - macOS
+        - Windows (Command Prompt)
+        - Windows (PowerShell)
+    validations:
+      required: true
+
+  - type: input
+    id: java_version
+    attributes:
+      label: Java version
+      description: Output of `java -version`
+      placeholder: openjdk 21.0.3
+    validations:
+      required: true
+
+  - type: input
+    id: command
+    attributes:
+      label: Command you ran
+      placeholder: ./runner.sh HelloWorld.java --watch
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: What happened
+      description: Paste the terminal output.
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected
+    validations:
+      required: true
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
new file mode 100644
index 0000000..f19a059
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -0,0 +1,27 @@
+name: Feature request
+description: Propose a new feature or improvement.
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: use_case
+    attributes:
+      label: Use case
+      description: What are you trying to do? What problem does this solve?
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: How would you expect this to work? Include flag names or command examples if relevant.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Any other approaches you considered, and why you prefer this one.
+    validations:
+      required: false
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..3d955af
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,40 @@
+# Contributing
+
+Contributions are welcome. This document covers how to report bugs, propose features, and submit pull requests.
+
+## Reporting a bug
+
+Open an issue using the Bug report template. Include the OS and Java version, the exact command you ran, and the output you got vs. what you expected.
+
+## Proposing a feature
+
+Open an issue using the Feature request template before writing any code. Describe the use case and how you would use it.
+
+## Submitting a pull request
+
+1. Fork the repository and create a branch from `main`.
+2. Make your changes.
+3. Run the test suite and confirm it passes on your platform:
+   ```bash
+   # Linux and macOS
+   chmod +x test.sh
+   ./test.sh
+
+   # Windows
+   test.bat
+   ```
+4. Open a pull request against `main`. Describe what changed and why.
+
+## Code style
+
+- `runner.sh`: `set -euo pipefail` stays on. Capture external command exit codes explicitly with `set +e / set -e`. Use the same ANSI color variables already defined. Keep bash 3.2 compatibility (no `mapfile`).
+- `runner.bat`: keep `setlocal EnableDelayedExpansion`. Use `!VAR!` inside blocks. Capture `ERRORLEVEL` immediately after the relevant command.
+- `runner.ps1`: use `$LASTEXITCODE` after every external command. Keep `Invoke-Run` returning the Java exit code.
+
+## Running CI locally
+
+The CI pipeline runs on Ubuntu, macOS, and Windows in parallel. To replicate a specific job locally, install JDK 21 and run `./test.sh` or `test.bat` depending on your platform.
+
+## License
+
+By contributing you agree that your changes will be licensed under the MIT license.
diff --git a/README.md b/README.md
index fa7869f..c16c973 100644
--- a/README.md
+++ b/README.md
@@ -265,8 +265,8 @@ The `examples/` folder contains three files you can use to verify the setup or a
 
 ### Phase 5 - Community
 
-- [ ] `CONTRIBUTING.md`
-- [ ] Issue templates
+- [x] `CONTRIBUTING.md`
+- [x] Issue templates
 
 ---