Skip to main content
Floci is MIT licensed and welcomes contributions of all kinds — bug reports, missing API actions, documentation improvements, and code.

​
Ways to contribute

  • Bug reports — open a GitHub issue with a minimal reproduction
  • Missing API actions — open a feature request describing the AWS behavior you need
  • Pull requests — new service implementations, bug fixes, or improvements
  • Documentation — clarifications, examples, and corrections are always welcome
  • Compatibility tests — add cases to the floci-compatibility-tests project

GitHub Issues

Report bugs or request missing AWS API actions.

GitHub Discussions

Feature ideas, compatibility questions, design tradeoffs — no idea too early.

Slack community

Ask questions, share feedback, and connect with other contributors.

Pull requests

Submit fixes, new service actions, or documentation improvements.

​
Development setup

1

Install prerequisites

You need:
  • Java 25+ — any distribution works. SDKMAN is a convenient way to install it:
curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"
sdk install java 25-open
  • Maven 3.9+ — the repo includes a Maven wrapper (./mvnw), so a separate installation is optional.
  • Docker — required for integration tests that spin up Lambda, RDS, and ElastiCache containers.
2

Clone the repository

git clone https://github.com/hectorvent/floci.git
cd floci
3

Run in dev mode

The Maven wrapper starts Quarkus with hot reload on port 4566:
./mvnw quarkus:dev
If you prefer your own Maven installation (3.9+), use mvn instead of ./mvnw.
4

Run the tests

# Run all tests
./mvnw test

# Run a single test class
./mvnw test -Dtest=SsmIntegrationTest

# Run a single test method
./mvnw test -Dtest=SsmIntegrationTest#putParameter

​
Commit message format

Floci uses Conventional Commits. semantic-release reads these to generate the changelog and version bumps automatically.
PrefixWhen to useVersion bump
feat:New AWS API action or serviceminor
fix:Bug fix or AWS compatibility correctionpatch
perf:Performance improvementpatch
docs:Documentation onlynone
chore:Build, CI, dependenciesnone
feat!: / BREAKING CHANGE:Incompatible changemajor
Examples: 
feat: add SQS SendMessageBatch action
fix: correct DynamoDB QueryFilter comparison operators
feat!: change default storage mode to persistent

​
Pull request checklist

  • ./mvnw test passes locally
  • New or updated integration test added for any changed behavior
  • Commit messages follow Conventional Commits
  • PR is focused — one feature or fix per PR
  • Related issues are referenced in the PR description
  • If no new tests are included, the PR description explains why
PRs that introduce new behavior must include tests. PRs that fix bugs should include a regression test where realistic. Documentation-only changes and low-risk refactors may omit tests, but the existing suite must still pass.
AGENT.md is the canonical agent instructions file for this repository. It contains the full architecture guide, protocol rules, and conventions for adding new services. If your coding agent expects a different filename, create a local symlink rather than copying it:
ln -s AGENT.md CLAUDE.md
ln -s AGENT.md GEMINI.md
ln -s AGENT.md COPILOT.md

​
Adding a new AWS service

See Architecture for the full protocol and package conventions. Quick summary:
  1. Create src/main/java/.../services/<service>/ with a Controller, Service, and model/ package
  2. Pick the right protocol (Query, JSON 1.1, REST JSON, or REST XML)
  3. Register the service in ServiceRegistry
  4. Add config entries in EmulatorConfig.java and application.yml
  5. Add *IntegrationTest.java tests
Always implement the real AWS wire protocol — never invent custom endpoints. The AWS SDK must work against Floci without modification.

​
Compatibility tests

For full SDK and CLI compatibility validation, use the floci-compatibility-tests companion project. It provides test suites across Java, Go, Node.js, Python, Rust, and the AWS CLI, and is the recommended starting point when verifying integration behavior end to end.

​
Reporting security issues

Do not open public GitHub issues for security vulnerabilities. Use GitHub private vulnerability reporting instead.

Build docs developers (and LLMs) love

Get started for freeTalk to us