Add CONTRIBUTING.md

[morissette]

Summary

Adds a CONTRIBUTING.md to guide new developers onboarding to the project.

What's covered

• Ways to contribute (code, docs, DMN rules, testing PRs)
• Project structure overview with the Java 17 vs 21 split called out explicitly
• Development environment setup for all four options (Codespaces, Devbox, Devcontainer, DIY)
• Service startup order and dependency chain
• Making changes (branching, commits, library metadata sync)
• Testing (Java unit tests, Bruno API tests, Playwright e2e)
• Code style (Prettier config, DMN naming conventions)
• PR submission process referencing CODEOWNERS
• Working with DMN files — step-by-step for adding benefits and checks, with naming constraints
• Deployment workflow for maintainers

Test plan

• Review document for accuracy against current project setup
• Verify all links resolve correctly
• Confirm DMN naming rules and Java version callouts are accurate
• Check that deployment steps match current maintainer workflow

🤖 Generated with Claude Code

[morissette]

Reviewed this against the source code. Overall the doc is solid — structure, service startup order, script paths, port numbers, Prettier config, CODEOWNERS, deploy triggers, and DMN naming conventions all check out. Found two issues that have been corrected in the latest push:

Bug fix: Java version claim was inaccurate

devbox.json only declares jdk21@latest — there is no JDK 17 in the Nix environment. The original doc said Devbox manages "Java 17, Java 21" which would mislead a contributor trying to understand the setup. In practice this works fine because library-api/pom.xml uses maven.compiler.release=17, so JDK 21 compiles it targeting Java 17 bytecode via --release 17. Updated the Devbox section, DIY section, and the Project Structure callout to reflect this accurately.

Bug fix: builder-api missing from Service URLs table

builder-api runs on port 8081 (confirmed in builder-api/.env) but wasn't in the reference table. Added it.

Everything else verified as accurate:

• All 5 service ports match firebase.json and process-compose.yml
• Startup order matches process-compose.yml dependency chain exactly
• All bin/ script paths exist
• Bruno test path library-api/test/bdt exists
• library-api-v* deploy trigger confirmed in .github/workflows/deploy-library-api.yml
• KIE DMN version 10.0.0 confirmed in builder-api/pom.xml
• Node 22 confirmed in devbox.json
• builder-frontend at 5173 confirmed in vite.config.js
• Firebase emulator project demo-bdt-dev confirmed in .firebaserc

[prestoncabe]

Thanks @morissette - I noticed a few small things, but otherwise good.

[earth-walker]

I think this is a great addition to the repo. it hits a lot of important points. I can see some room for improvement in the future. for me it's a bit long and misses some important points about how we work on slack, how the project is associated with Code For Philly, etc. (or maybe they are in there somewhere but too far down for me to have noticed while skimming through). that said I support merging this version and updating it in the future, as I also felt we should really have a document like this.