Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
205 lines (131 loc) · 3.39 KB

CONTRIBUTING.md

File metadata and controls

205 lines (131 loc) · 3.39 KB

Contributing Guide

Thanks for your interest in improving openapi-generics! This repository provides a contract-first, generics-aware OpenAPI platform, centered around a deterministic API lifecycle:

Contract → OpenAPI projection → Code generation

Built with:

  • Java 17+
  • Spring Boot 3.4.x, 3.5.x 4.x
  • OpenAPI Generator 7.x

Be kind. Be constructive. See our Code of Conduct.

Table of contents

Questions & Support

Have a question, design idea, or usage concern?

  • Use GitHub Discussions → Ideas for:

    • API contract design
    • generics handling (ServiceResponse<T>, Page<T>)
    • projection behavior

  • Use GitHub Discussions → Q&A for:

    • setup and configuration
    • integration questions
    • generator usage

  • Found a bug?

    • Open an Issue with a minimal reproduction

Please search existing issues and discussions first.

How to contribute

  1. Fork and create a branch:
git checkout -b feature/scope-short-title
  1. Keep changes small and focused
  2. Update tests and docs if behavior changes
  3. Run full build
  4. Open PR with clear explanation

Small PRs = faster review

Development setup

Prerequisites

  • Java 17+ (21 recommended)
  • Maven 3.9+

Build (core platform)

mvn -q -ntp clean verify

Project layout

/openapi-generics-contract
/openapi-generics-platform-bom
/openapi-generics-server-starter
/openapi-generics-java-codegen
/openapi-generics-java-codegen-parent

Coding style & commits

Rules

  • Keep code minimal and deterministic

  • Do NOT patch generated output

  • Fix issues at:

    • contract
    • projection
    • generator

Commit prefixes

  • feature:
  • bugfix:
  • docs:
  • refactor:
  • test:
  • ci:

Testing & coverage

mvn clean verify

Notes:

  • Core modules focus on correctness, not runtime apps
  • Integration validation happens via sample consumers (external)

Architecture principles (important)

These are not guidelines — they are invariants.

This project follows strict boundaries:

1. Contract is the source of truth

  • ServiceResponse<T> defines semantics
  • OpenAPI must be a projection (not authority)

2. Determinism

Same input → same output

No hidden behavior

3. No duplication

  • Contract defined once
  • No re-definition in OpenAPI or generated code

4. Generated code is disposable

Never fix issues in generated files

Fix:

  • contract
  • projection
  • templates

Pull Request checklist

  • Scope is minimal
  • Build passes
  • Tests updated if needed
  • Docs updated if needed
  • No generated code edits

Labels we use

  • enhancement
  • bug
  • documentation
  • good first issue
  • help wanted

Security

Do NOT open public issues for vulnerabilities

See SECURITY.md

License

MIT License