CONTRIBUTING.md

Contributing to java-obs-agent

Thanks for your interest! This is a small project - please keep PRs focused.

Setup

• JDK 21+ required to run ./gradlew (the build targets Java 17 bytecode but needs JDK 21 on the toolchain). Any JDK 21+ works; GraalVM 21 was used during development.
• Gradle is wrapped - just use ./gradlew (no global Gradle install needed).

# build
JAVA_HOME=<path-to-jdk-21> ./gradlew :obs-agent-core:build
# unit tests
JAVA_HOME=<path-to-jdk-21> ./gradlew :obs-agent-core:test
# e2e (real -javaagent attach + MCP)
JAVA_HOME=<path-to-jdk-21> ./gradlew :obs-agent-core:test --tests 'io.obsagent.EndToEndSmokeTest' -Pe2e=true
# shaded agent jar
JAVA_HOME=<path-to-jdk-21> ./gradlew :obs-agent-core:shadowJar

Code style

• Java 17 features are fine. Keep the agent dependency-light: shaded ByteBuddy + Jackson; slf4j is compileOnly (so the agent can read the host's Logback/MDC).
• ByteBuddy advice must access only public static members - it gets inlined into target classes in other packages; package-private access throws IllegalAccessError at runtime. See docs/superpowers/specs/.
• Never throw into instrumented user code - wrap all advice in try/catch.
• Keep tools read-only by default; anything mutating the target JVM goes behind the enableInstrumentation gate + PermissionGuard.
• Add/adjust tests for new behavior. Run ./gradlew :obs-agent-core:test before opening a PR.

Commit messages

Conventional Commits, scoped to match the existing history, e.g.:

• feat(tools): add <tool>
• fix(instr): <what was wrong>
• fix(chat): <what>
• docs: <area>
• chore: <area>

Pull requests

• Open a PR against main.
• Keep changes focused; one logical change per PR.
• Don't bump the version in a feature PR unless discussed first.

License

By contributing, you agree that your contributions are licensed under the Apache License, Version 2.0 (see LICENSE).