Contributing¶
Issues and pull requests are welcome at github.com/brbrown25/flink-proto-confluent. Open an issue first for anything non-trivial.
Tests use JUnit 5 and real components (Testcontainers for Kafka and Schema Registry); Mockito is not used. Commits follow Conventional Commits, which drives release-please.
Working on these docs¶
The site is MkDocs Material. Sources are in docs/content/, config in docs/mkdocs.yml, and the nav is the nav: list in that file — a new page must be added there.
Preview locally¶
python3 -m venv .venv && .venv/bin/pip install -r docs/requirements.txt
cd docs
../.venv/bin/mkdocs serve # http://127.0.0.1:8000, live reload
../.venv/bin/mkdocs build --strict # exactly what CI runs; fails on broken links/nav
When to update what¶
| You changed | Update |
|---|---|
| A format option, default or validation rule | reference/configuration.md and any how-to that shows it |
| User-visible behaviour or an error message | The relevant how-to; re-record a cast if it appears in one |
| The dependency version | Nothing — release-please bumps the version markers in getting-started.md and the README on release |
| Output shown in a demo | Re-record that cast (below) |
Keep SQL snippets in the docs identical to the SQL in docs/demo/sql/ where both exist.
Terminal demos (asciinema)¶
Casts in docs/content/assets/casts/ are recorded against a real Kafka + Schema Registry + Flink stack defined in docs/demo/. Requires Docker, asciinema 3.x and a JDK.
cd docs/demo
./record.sh # rebuilds the JAR, resets the stack, re-records every cast
asciinema play ../content/assets/casts/quickstart.cast # preview one in the terminal
To add a cast: write docs/demo/casts/<name>.sh (copy an existing one; say prints a comment, run types and executes a command), add any SQL to docs/demo/sql/, add <name> to the ALL list in record.sh, then embed it in demos.md:
Record just some casts with ./record.sh name1 name2, which reuses the demo stack if it is already healthy (about a minute per cast instead of a full rebuild). Casts reuse state from earlier runs, such as topics and schema ids, so use ./record.sh --reset name1 or a full ./record.sh before committing a recording. CASTS="name1 name2" ./record.sh still works and always resets. You can also dry-run a script without the typing delays with CAST_FAST=1 ./casts/<name>.sh (against a running stack). Keep casts under ~45 seconds. See docs/demo/README.md for the stack itself.
Publishing¶
Pushes to main that touch docs/** build and deploy the site to GitHub Pages via .github/workflows/docs.yml. Pull requests run the same strict build without deploying.
Maintainers: the release process is documented in RELEASING.md and CI ownership in ci.md.