Contributing
floci-gcp is MIT licensed and welcomes contributions of all kinds.
Ways to Help
- Bug reports: open a GitHub issue with a minimal reproduction
- Missing API operations: open a feature request
- Pull requests: new service operations, bug fixes, documentation improvements
Development Setup
# Clone
git clone https://github.com/floci-io/floci-gcp.git
cd floci-gcp
# Run in dev mode (hot reload, port 4588)
./mvnw quarkus:dev
# Run all tests
./mvnw test
# Run a specific test
./mvnw test -Dtest=GcsIntegrationTest
./mvnw test -Dtest=PubSubIntegrationTest#publishMessage
Commit Message Format
This project uses Conventional Commits.
Format
| Type | Effect |
|---|---|
feat |
New feature → minor version bump |
fix |
Bug fix → patch version bump |
perf |
Performance improvement → patch |
docs |
Documentation only → no version bump |
chore |
Build/CI/housekeeping → no version bump |
refactor |
Code restructure → no version bump |
test |
Adding/updating tests → no version bump |
ci |
CI workflow changes → no version bump |
feat!: or BREAKING CHANGE: |
Breaking change → major bump |
Valid examples ✅
feat(pubsub): add StreamingPull support
fix(gcs): correct multipart upload final response
chore: release 1.2.0
feat!: remove legacy endpoint
ci: add conventional commits lint workflow
Invalid examples ❌
Add streaming support # missing type
Feature: add something # not a valid type
feat : space before colon # space before colon
FIX(gcs): uppercase type # type must be lowercase
Adding a New GCP Service
See AGENTS.md for the full architecture guide.
Quick summary:
- Identify the GCP wire protocol (gRPC or REST)
- Create
src/main/java/io/floci/gcp/services/<service>/with a Controller, Service, andmodel/package - For gRPC: extend the generated
*Grpc.*ImplBaseand useGcpGrpcController.grpcErrorfor shared error mapping; for REST: use JAX-RS@Pathresources - Register the service in
ServiceRegistry - Add config in
EmulatorConfig.javaandapplication.yml - Add
*IntegrationTest.javatests - Validate against the GCP SDK client
Pull Request Checklist
- [ ]
./mvnw testpasses - [ ] New or updated integration test added
- [ ] Tests validate behavior with GCP SDK clients, not just raw HTTP
- [ ] Commit messages follow Conventional Commits
- [ ] No
Co-Authored-Bytrailers for AI tools
Please keep no more than 4 open pull requests, drafts included, and no more than 2 of them ready for review. A bot turns a 3rd ready PR back into a draft and closes new ones opened while you already have 4 open. See CONTRIBUTING.md for details.
Compatibility Tests
The ./compatibility-tests/ directory contains SDK-based integration tests. Run them before submitting changes that affect GCP protocol behavior:
cd compatibility-tests
cp env.example .env
just setup
just test-all # SDK suites (Java, Ruby, Python, Node, Go, Rust)
just test-gcloud # gcloud CLI suite
just test-all-iac # Terraform / OpenTofu
If the compatibility test suite is unavailable in your environment, state that explicitly in the PR description.
Releases
Stable releases ship on the 15th and the last day of each month. Merging to main does not cut a release: the change rides the next train, and reaches the nightly image on the next nightly build.
Releases are cut from main by the Release Cut workflow, scheduled at 00:30 US Central time on those days (maintainers can also run it by hand). It runs semantic-release over the Conventional Commits since the last tag. That is why the commit type matters: feat: and fix: move the version, docs: and chore: do not. CHANGELOG.md is generated from those messages and is not edited by hand; a genuine correction goes in a PR carrying the changelog-edit label.
Reporting Security Issues
Do not open public issues for security vulnerabilities. Use GitHub private vulnerability reporting instead.