feat: add files for contributing

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,55 @@
+---
+name: Bug report
+about: A parsing or emission bug — wrong, missing, or invalid OpenAPI output
+title: 'bug: '
+labels: bug
+---
+
+<!--
+Security-sensitive reports (crashes on crafted input, dropped security schemes,
+path traversal) go to the private channel in responsible_disclosure.md —
+please do NOT open a public issue for those.
+-->
+
+## Minimal reproduction
+
+<!-- The smallest annotated Go snippet that reproduces the issue.
+     A single handler with its comment block is usually enough. -->
+
+```go
+// ShowAccount godoc
+//
+// @Summary  ...
+// @Router   /accounts/{id} [get]
+func ShowAccount(w http.ResponseWriter, r *http.Request) {}
+```
+
+## Command
+
+<!-- The exact oasgen invocation, including flags and target OpenAPI version. -->
+
+```sh
+oasgen -d . -o openapi.json -oas 3.2.0
+```
+
+## Actual output
+
+<!-- The relevant fragment of the emitted document (or the error/panic). -->
+
+```json
+```
+
+## Expected output
+
+<!-- What you expected instead, ideally with a reference: a section of the
+     OpenAPI specification (https://spec.openapis.org/) or swag's behavior
+     for the same annotations. -->
+
+```json
+```
+
+## Environment
+
+- `openapi-parser` version / commit:
+- Go version (`go version`):
+- OS:

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,6 @@
+---
+blank_issues_enabled: true
+contact_links:
+  - name: Security report
+    url: https://github.com/indykite/openapi-parser/blob/master/responsible_disclosure.md
+    about: Please report security-sensitive issues privately — see the responsible disclosure policy, not a public issue.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,34 @@
+---
+name: Feature request
+about: A new annotation, directive, type-resolution rule, or OpenAPI construct
+title: 'feat: '
+labels: enhancement
+---
+
+## What should be supported
+
+<!-- Describe the annotation, Go construct, or OpenAPI feature. If it exists
+     in swag, name it; if it's an OpenAPI 3.1/3.2 construct, link the relevant
+     section of the specification (https://spec.openapis.org/). -->
+
+## Example input
+
+<!-- The annotation or Go code as you'd want to write it. -->
+
+```go
+```
+
+## Expected output
+
+<!-- The OpenAPI fragment it should emit, and for which spec versions
+     (3.1, 3.2, or both). If the construct only exists in one version,
+     say what the other version should fall back to. -->
+
+```json
+```
+
+## Alternatives / workarounds
+
+<!-- How you handle this today, if at all. Note that changes requiring a
+     third-party dependency won't be accepted — the module is stdlib-only
+     by design (see CONTRIBUTING.md). -->

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,50 @@
+# Pull request
+
+<!--
+Thanks for opening a PR. Please fill in the sections below — reviewers use them
+to triage and to write the eventual changelog entry. Empty PRs without context
+get bounced.
+
+If anything here doesn't apply (e.g. doc-only change), say so explicitly rather
+than deleting the section.
+-->
+
+## What this PR does
+
+<!-- One sentence. Lead with the verb: "Add ...", "Fix ...", "Tighten ...".
+     Name the affected stage where relevant (lexer, parser, schema resolver, emitter). -->
+
+## Effect on annotations and output
+
+<!-- Required for any change to parsing or emission. Which annotations or Go
+     constructs are affected, and how does the emitted OpenAPI document change?
+     Call out explicitly:
+     - any change to how an existing swag annotation is interpreted
+     - any change to emitted output for existing inputs (breaking vs additive)
+     - which OpenAPI versions are affected (3.1, 3.2, or both) -->
+
+## How it was tested
+
+<!-- Be specific. List the tests added or updated, and paste relevant output.
+     If the change affects generated output, run the parity gate against an
+     annotated repo and note the result: `make parity REPO=path/to/repo`. -->
+
+- [ ] `make test` passes
+- [ ] `make lint` passes
+- [ ] Tests added/updated for the new behavior (positive case + edge case)
+- [ ] `make parity` run (if output-affecting) — repo and result:
+
+## Known gaps or follow-ups
+
+<!-- Anything intentionally out of scope: missing edge cases, unsupported
+     annotation forms, features deferred to a follow-up PR.
+     Better to surface than to surprise. -->
+
+## Checklist
+
+- [ ] One fix or feature per PR — no unrelated changes bundled in.
+- [ ] PR title follows the existing convention (e.g. `feat: add @tag.parent support`, `fix: nullable pointer emission for 3.1`).
+- [ ] No new entries in `go.mod` — the module is stdlib-only by design (see [`CONTRIBUTING.md`](../CONTRIBUTING.md#ground-rules)); if a dependency is unavoidable, it was agreed in an issue first.
+- [ ] Breaking changes to annotation interpretation or emitted output are called out in the title and body.
+- [ ] No secrets, internal URLs, or personal data committed.
+- [ ] I have the right to contribute this content under the repo's [LICENSE](../LICENSE).

CODEOWNERS

@@ -0,0 +1,20 @@
+# Each line is a file pattern followed by one or more owners.
+# Later match takes precedence over earlier rule.
+
+# Global rule set for everything
+*   @indykite/devx
+
+#
+# CI/CD, SAST & linting configs
+/.github/               @indykite/devx @indykite/ops
+.pre-commit-config.yaml @indykite/devx @indykite/ops
+.golangci.yml           @indykite/devx @indykite/ops
+.checkov.yaml           @indykite/devx @indykite/ops
+.deepsource.toml        @indykite/devx @indykite/ops
+.hadolint.yaml          @indykite/devx @indykite/ops
+.shellcheckrc           @indykite/devx @indykite/ops
+.trivy.yaml             @indykite/devx @indykite/ops
+.trivy_data.yaml        @indykite/devx @indykite/ops
+.trivyignore.yaml       @indykite/devx @indykite/ops
+.yamlfmt.yml            @indykite/devx @indykite/ops
+.yamllint.yml           @indykite/devx @indykite/ops

CONTRIBUTING.md

@@ -0,0 +1,81 @@
+# Contributing
+
+Thanks for your interest in improving `openapi-parser`. When contributing to this repository, please first discuss any non-trivial change via an issue before opening a pull request — a 30-second sanity check from a maintainer can save an afternoon of work.
+
+## Before you start
+
+- Read the [README](./README.md) to understand the pipeline (`extract.go` → `lexer.go` → `parse.go` → `schema.go` → `emit.go`) and the version-agnostic model in the middle.
+- Check open issues and PRs to make sure the change isn't already in flight.
+- Read [`responsible_disclosure.md`](./responsible_disclosure.md) if your contribution touches anything security-sensitive. Do **not** open a public issue for security reports.
+
+## Ground rules
+
+- **Stdlib only, by design.** The module has no third-party dependencies and no swag dependency: parsing uses `go/parser` + `go/ast`, emission uses `encoding/json` plus the minimal internal
+  YAML encoder (`gen/yaml.go`). PRs that add a dependency to `go.mod` will be rejected unless discussed and agreed in an issue first.
+- **swag compatibility matters.** Existing swag-style annotations must keep working. If a change alters how an annotation is interpreted, call that out explicitly in the PR.
+- **Spec-version separation.** Annotation syntax and output spec version evolve independently. Parser/model changes belong in `parse.go`/`schema.go`; version-specific output belongs in the emitter.
+
+## Development setup
+
+You need Go 1.26 or later.
+
+```sh
+git clone https://github.com/indykite/openapi-parser
+cd openapi-parser
+
+make install-tools   # gci + golangci-lint
+go build ./...
+make test
+```
+
+Optionally install the pre-commit hooks (`pre-commit install`) so formatting and lint run automatically.
+
+## Making changes
+
+1. Fork the repository and branch off `master`.
+2. Make your change, keeping it focused: one fix or feature per PR.
+3. Add or update tests. Parser and emitter behavior is covered by tests under `gen/` with fixtures in `testdata/`; new directives or type-resolution rules need both a positive case and an edge case.
+4. Run the checks locally before pushing:
+
+   ```sh
+   make fmt      # gofmt
+   make gci      # import ordering
+   make lint     # golangci-lint
+   make test     # go test ./...
+   ```
+
+5. If your change affects generated output, run the parity gate against a repo you have access to and note the result in the PR:
+
+   ```sh
+   make parity REPO=path/to/annotated-repo
+   ```
+
+   Any repo with swag-style annotations and a checked-in baseline works: the tool speaks of "services", but that just means any directory with its own
+   `docs/swagger.yaml`; a single-binary repo counts as one service at its root (see [README § Parity gate](./README.md#parity-gate-cmdoasparity)).
+
+## Pull requests
+
+- Keep one fix or feature per PR; reviewers should not have to evaluate unrelated changes together.
+- Use a descriptive title following the existing convention, e.g. `feat: add @tag.parent support` or `fix: nullable pointer emission for 3.1`.
+- The body should answer: what does this change do, why is it needed, and how was it tested?
+- Breaking changes to annotation interpretation or emitted output must be called out explicitly in the PR title and body.
+- By submitting a PR you confirm you have the right to contribute the content under this repo's [Apache-2.0 LICENSE](./LICENSE).
+
+## Reporting bugs
+
+A good parser bug report contains:
+
+1. A minimal annotated Go snippet that reproduces the issue.
+2. The `oasgen` invocation used (flags, target OpenAPI version).
+3. The output you got and the output you expected (ideally referencing the [OpenAPI specification](https://spec.openapis.org/) or swag's behavior).
+
+## Code of conduct
+
+Be kind. We follow the spirit of the [Contributor Covenant](https://www.contributor-covenant.org/) v2.1:
+
+- Assume good faith; critique the work, not the person.
+- Be specific and actionable in reviews: vague negativity wastes everyone's time.
+- Welcome newcomers; point them at this guide rather than dismissing the PR.
+- Harassment, discriminatory language, doxxing, or sustained bad-faith argument are not tolerated and are grounds for a ban.
+
+To report a conduct issue privately, use the contact address in [`responsible_disclosure.md`](./responsible_disclosure.md); reports are kept confidential among the maintainers handling the case, and good-faith reports will never be held against you.

GNUmakefile

@@ -35,8 +35,9 @@ tidy:
 	go mod tidy
 
 # Compare oasgen output against swag-generated docs in another repository.
-# Services are auto-discovered by their docs/swagger.yaml; pass SERVICES to
-# restrict the list. Example: make parity REPO=../my-platform
+# A "service" is any directory with its own docs/swagger.yaml baseline; they
+# are auto-discovered, and a single-binary repo has one at its root. Pass
+# SERVICES to restrict the list. Example: make parity REPO=../my-platform
 parity:
 	@test -n "$(REPO)" || { echo "usage: make parity REPO=path/to/repo [SERVICES=dir1,dir2]"; exit 2; }
 	@echo "==> Checking op/schema parity against swag output in $(REPO)..."