Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
102 lines (68 loc) · 2.97 KB

CONTRIBUTING.md

File metadata and controls

102 lines (68 loc) · 2.97 KB
Raw

Contributing to Java Parser Check

Thanks for your interest in helping with Java Parser Check! Every contribution is welcome, whether it is a bug report, a better diagnostic message, a test, documentation, or a new feature.

Ways to help

  • Report a bug or confusing diagnostic
  • Add tests for YAML edge cases
  • Improve error messages or documentation
  • Suggest a feature or a better API
  • Fix an existing issue
  • Add support for a useful validation rule

Reporting a bug

Please include enough detail for someone else to reproduce the problem:

  • the YAML input, with secrets removed
  • the expected behavior
  • the actual diagnostic or exception
  • the Java and Gradle versions
  • a small code sample, if relevant

Small, focused examples are especially helpful. If possible, include a test case that demonstrates the issue.

Suggesting a feature

Before opening a feature request, please describe the problem first:

  1. What are you trying to validate or diagnose?
  2. Why is the current API not enough?
  3. What would a simple usage example look like?

Features should keep the main API easy to use and should produce diagnostics that are useful to developers, not just technically correct parser errors.

Local development

Requirements:

  • Java 8+ to use the library
  • JDK 17+ to run Gradle 9.7.1 and build the project

Run the test suite with:

gradle test

You can generate the Gradle wrapper for your environment if needed:

gradle wrapper --gradle-version 9.7.1
./gradlew test

Adding tests

Please add tests for behavior that you change or introduce. Good diagnostic tests usually verify:

  • whether the report is valid or invalid
  • the diagnostic code
  • the severity
  • the important part of the message
  • the source line or column when location matters

Try to test one behavior per test and include YAML edge cases when they are relevant.

Adding diagnostic codes

Diagnostic codes are part of the public developer experience. When adding a new one:

  • use the existing JPC-<AREA>-<NUMBER> style
  • do not reuse an existing code for a different problem
  • explain the problem in plain language
  • include a useful suggestion when possible
  • document the code in README.md
  • add a regression test

Avoid changing an existing code or message unnecessarily. Tools may use diagnostic codes to group or filter problems.

Pull requests

Before opening a pull request, please check that:

  • the project builds and tests pass
  • new behavior has tests
  • public API changes are documented
  • diagnostics remain actionable and easy to understand
  • the pull request explains what changed and why

Keep pull requests focused. Smaller changes are easier to review and merge.

Code style

Follow the style already used in the project:

  • prefer clear names over clever abstractions
  • keep public APIs small and predictable
  • avoid unrelated refactors in feature pull requests
  • add comments only when they explain non-obvious intent

Thank you for helping make YAML failures easier to understand.