diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 00000000..8c9a73aa --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,35 @@ +name: Bug report +description: Report a problem with the browser, setup guide, scripts, or documentation. +title: "[Bug]: " +labels: + - bug +body: + - type: textarea + id: problem + attributes: + label: Problem + description: What happened? + validations: + required: true + - type: textarea + id: steps + attributes: + label: Steps to reproduce + description: Include the browser, command, or file you used. + placeholder: | + 1. Open index.html + 2. Search for ... + 3. See ... + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected behavior + validations: + required: true + - type: input + id: environment + attributes: + label: Environment + placeholder: "Chrome 126, macOS 15 / Node 20" diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..0086358d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1 @@ +blank_issues_enabled: true diff --git a/.github/ISSUE_TEMPLATE/data_issue.yml b/.github/ISSUE_TEMPLATE/data_issue.yml new file mode 100644 index 00000000..06625d3b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/data_issue.yml @@ -0,0 +1,29 @@ +name: Data issue +description: Report an exercise metadata, instruction, translation, or media-reference problem. +title: "[Data]: " +labels: + - data +body: + - type: input + id: exercise-id + attributes: + label: Exercise ID + description: The `id` from `data/exercises.json`, if known. + placeholder: "0001" + - type: input + id: exercise-name + attributes: + label: Exercise name + placeholder: "3/4 sit-up" + - type: textarea + id: problem + attributes: + label: Problem + description: Describe what is wrong and what you expected instead. + validations: + required: true + - type: textarea + id: suggested-fix + attributes: + label: Suggested fix + description: Optional. Include source or reasoning if you know the correct value. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..7d355947 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,21 @@ +## Summary + +- Describe the change and why it is needed. + +## Type of change + +- [ ] Dataset change +- [ ] Documentation change +- [ ] Tooling / validation change +- [ ] Browser UI change +- [ ] Example / integration change + +## Validation + +- [ ] I ran `node scripts/validate-dataset.mjs` +- [ ] I preserved Gym visual attribution and media-license requirements +- [ ] I manually checked affected browser pages, if applicable + +## Notes for reviewers + +- Include any review context, follow-up work, or known limitations. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..07926eac --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,47 @@ +# Contributing + +Thanks for helping improve the exercises dataset. Keep changes small, reviewable, and focused on data quality, tooling, or documentation. + +## Before opening a PR + +1. Confirm your change is allowed by the media license in `LICENSE` and `NOTICE.md`. +2. Run the dataset validator: + + ```bash + node scripts/validate-dataset.mjs + ``` + +3. If you are changing schema or validation behavior, check open pull requests first to avoid duplicating active work. + +## Dataset rules + +- Keep every exercise `id` unique and formatted as four digits, for example `0001`. +- Keep `image` and `gif_url` paths aligned with `id` and `media_id`: + - `images/-.jpg` + - `videos/-.gif` +- Keep all six instruction languages populated: `en`, `es`, `it`, `tr`, `ru`, and `zh`. +- Keep both `instructions` and `instruction_steps` in sync when editing exercise instructions. +- Keep `secondary_muscles` as an array of strings. +- Keep the exact media attribution in every record: `© Gym visual — https://gymvisual.com/`. + +Duplicate exercise names are allowed only when the records represent distinct media or movement variants. The validator reports them as warnings so reviewers can inspect them. + +## Media rules + +The `images/` and `videos/` assets are not covered by the MIT license. They are included with separate permission from Gym visual at 180x180 resolution. Do not replace, upscale, redistribute, or add media unless you have confirmed the rights and attribution requirements. + +## Browser checks + +If you edit `index.html`, manually verify: + +- Search filters the exercise grid. +- Category, equipment, and target filters work. +- Infinite scroll appends more exercises. +- Exercise modals show media, metadata, muscles, and language tabs. + +If you edit `setup.html`, manually verify: + +- Database tabs switch SQL dialects. +- SQL generation downloads a file. +- API language tabs update examples. +- The LLM prompt updates when framework or database options change. diff --git a/README.md b/README.md index 33e86c9f..ac53f1ec 100644 --- a/README.md +++ b/README.md @@ -47,6 +47,7 @@ - [Data Schema](#-data-schema) - [Sample Exercises](#-sample-exercises) - [Usage Examples](#-usage-examples) +- [Contributing](#-contributing) - [License & Use](#-license--use) --- @@ -409,6 +410,20 @@ console.log("First 6 exercises:", randomWorkout.map(e => e.name)); --- +## 🤝 Contributing + +Before opening a pull request, run the dataset validator: + +```bash +node scripts/validate-dataset.mjs +``` + +The validator checks JSON structure, required fields, multilingual instructions, duplicate IDs, media references, missing media files, and orphan media files. Duplicate exercise names are reported as warnings because some records may represent distinct movement or media variants. + +See [`CONTRIBUTING.md`](CONTRIBUTING.md) for dataset rules, media-license requirements, and browser verification notes. + +--- + ## 📄 License & Use This repository is a **developer setup wizard and structured exercise dataset** — exercise metadata, multilingual instruction translations, and 180×180 exercise media.