diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.yml new file mode 100644 index 0000000..725e2ff --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug-report.yml @@ -0,0 +1,59 @@ +name: Spec bug report +description: Report a problem in the OpenAPI specification, generated output, or repository docs. +title: "[Bug] " +labels: + - bug +body: + - type: markdown + attributes: + value: | + Before opening an issue, check for existing issues or pull requests covering the same problem. + + Use this template for incorrect behavior, invalid schema definitions, broken examples, or documentation problems. + - type: textarea + id: summary + attributes: + label: Summary + description: Describe the problem clearly and concisely. + placeholder: The schema for ... does not match the documented example. + validations: + required: true + - type: input + id: affected-area + attributes: + label: Affected area + description: Reference the relevant path, schema, component, or documentation section if known. + placeholder: paths/chat.yml or components/schemas/FeedbackResponse + validations: + required: true + - type: textarea + id: current-behavior + attributes: + label: Current behavior + description: Explain what is wrong in the current spec or docs. + placeholder: The request body marks field `x` as required, but the example omits it. + validations: + required: true + - type: textarea + id: expected-behavior + attributes: + label: Expected behavior + description: Explain what the correct behavior or definition should be. + placeholder: Field `x` should be optional, or the example should include it. + validations: + required: true + - type: textarea + id: supporting-context + attributes: + label: Supporting context + description: Add example payloads, validation output, screenshots, or links that help reproduce or understand the issue. + render: markdown + validations: + required: false + - type: textarea + id: additional-notes + attributes: + label: Additional notes + description: Include constraints, related discussions, or follow-up considerations. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..3ba13e0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1 @@ +blank_issues_enabled: false diff --git a/.github/ISSUE_TEMPLATE/spec-change.yml b/.github/ISSUE_TEMPLATE/spec-change.yml new file mode 100644 index 0000000..0e04be7 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/spec-change.yml @@ -0,0 +1,67 @@ +name: Spec change proposal +description: Propose a new endpoint, schema change, clarification, or other API specification update. +title: "[Proposal] " +labels: + - enhancement +body: + - type: markdown + attributes: + value: | + Use this template for non-trivial API or documentation changes. + + A focused proposal makes review faster and reduces ambiguity during implementation. + - type: textarea + id: problem + attributes: + label: Problem or goal + description: Describe the problem to solve or the improvement you want to make. + placeholder: Consumers need a way to ... + validations: + required: true + - type: input + id: affected-area + attributes: + label: Affected area + description: List the relevant endpoints, schemas, or documentation sections if known. + placeholder: /feedback, components/schemas/Submission, README + validations: + required: true + - type: textarea + id: proposed-change + attributes: + label: Proposed change + description: Describe the concrete change you want in the spec. + placeholder: Add a new optional field ... or clarify the response contract for ... + render: markdown + validations: + required: true + - type: textarea + id: examples + attributes: + label: Example payloads or schema snippets + description: Provide sample requests, responses, or schema fragments where useful. + render: yaml + validations: + required: false + - type: textarea + id: impact + attributes: + label: Compatibility and impact + description: Note whether this is breaking, additive, or documentation-only, and mention downstream impact if known. + placeholder: Additive change; existing consumers should continue to work unchanged. + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: Describe other options you evaluated or reasons for rejecting them. + validations: + required: false + - type: textarea + id: additional-notes + attributes: + label: Additional notes + description: Include related issues, constraints, or open questions. + validations: + required: false diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..682026e --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,21 @@ +## Summary + +Describe the change and why it is needed. + +## Related issue + +Link the related issue if one exists. + +## Scope + +- [ ] This pull request is focused on a single concern. +- [ ] The change was started from the latest `main` branch, or from a fork if direct branch creation is not available. + +## Validation + +- [ ] `npm run lint` +- [ ] `npm run bundle` + +## Notes for reviewers + +Call out anything that needs extra attention during review, including compatibility concerns, open questions, or follow-up work. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..0b67df7 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,60 @@ +# Contributing + +This repository contains the OpenAPI specification for the µEd API. Contributions should keep the source files consistent and go through GitHub pull requests. + +## Creating issues + +Before opening a new issue, check whether the topic is already covered by an existing issue or pull request. + +When creating an issue, include: + +- a clear, specific title +- the problem you observed or the change you want to propose +- the relevant part of the specification, if known +- example requests, responses, or schema snippets when they help clarify the change +- expected behavior and any constraints or open questions + +Use issues to capture bugs, unclear parts of the specification, and proposed API changes before implementation when the scope is non-trivial. + +## Contributing + +1. Start from the latest `main` branch. +2. Create a topic branch for your work. +3. If you do not have permission to create branches in this repository, fork the repository and open the pull request from your fork. +4. Make your changes in the source spec files. +5. Run the local checks before opening or updating a pull request: + +```bash +npm install +npm run lint +npm run bundle +``` + +When you open the pull request: + +- describe the change and why it is needed +- link the related issue when one exists +- keep the pull request focused on a single concern + +## Reviewing + +Reviewers should check that: + +- the proposed change is clear and scoped appropriately +- the OpenAPI source remains consistent and readable +- `npm run lint` passes +- `npm run bundle` succeeds when applicable + +Pull request authors should respond to review comments by updating the branch or clarifying intent in the discussion. + +## Merging + +Pull requests should be merged with **Squash and merge**. + +Before merging: + +- the pull request has been reviewed +- the GitHub CI checks for linting and bundling are passing +- open review comments have been resolved + +Merged branches are deleted automatically. diff --git a/README.md b/README.md index ca2db84..958bb34 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,6 @@ This repository is intentionally **spec-only**. It defines an **OpenAPI 3.1** co - `openapi.yml` — the main entry point (OpenAPI 3.1) - `paths/` — endpoint definitions (multi-file structure) -- `dist/openapi.yml` — bundled single-file spec (generated) ## What the spec covers @@ -45,4 +44,10 @@ npm run bundle ## Viewing the spec -Open `openapi.yml` (or `dist/openapi.yml` for the bundled version) in any OpenAPI-capable tool (e.g., Swagger Editor, Swagger UI, Stoplight, Redocly) to render and explore the docs. +The published spec is also available in an online viewer at [mued.org/spec](https://mued.org/spec/). + +For local viewing, open `openapi.yml` in any OpenAPI-capable tool (e.g., Swagger Editor, Swagger UI, Stoplight, Redocly). If you want a single-file version, run `npm run bundle` first and then open `dist/openapi.yml`. + +## Contributing + +Contributor workflow guidance for issues, branching, reviews, and merging lives in [CONTRIBUTING.md](CONTRIBUTING.md).