Zakaria El OrcheandClaude Opus 5
424ca31b7a
Boots a real app on an OS-assigned port for a test class or a single test and
hands back a client pointed at it:
@RegisterExtension
static FlashTest app = FlashTest.of(new BlogApp())
.mock(UserService.class, new InMemoryUserService());
app.get("/api/users").expectStatus(200).expectBodyContains("alice");
A field rather than an annotation, because annotation values are compile-time
constants and so could never express a second server wired from the first —
FlashTest.of(new BlogApp(auth.baseUri())). Startup is lazy, so reading
baseUri() boots that server on the spot and declaration order does the wiring,
with no dependence on JUnit's extension ordering. A static field boots once per
class, a non-static field once per test; that is stock JUnit field semantics
rather than an option to configure.
Runs against a real loopback port instead of dispatching in-process. An
in-process dispatcher would be a third copy of the routing/handler/exception
sequence that Http1Connection and Http2StreamDispatcher already duplicate, kept
in sync by hand, and it would let a test pass while the status line,
content-length or HPACK encoding was broken.
mock() installs overrides as the last extension, after everything the
application and its extensions declare, so a fake always wins. Any object is
accepted, so a hand-written fake and a Mockito mock are equally welcome and
this module depends on no mocking library — only flash and junit-jupiter-api.
Teardown cancels the client before stopping the server: HttpClient holds
keep-alive sockets open and ServerLifecycle.stop() spins until the last one
closes, so the default 15s drain would otherwise be paid on every test class.
shutdownNow rather than close(), which blocks until every operation completes
and would hang on a leaked WebSocket.
Lives at the top level, not under flash-extensions/, which holds things you
install() onto an app; this carries junit-jupiter-api at compile scope and
nothing installable should.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
122 lines
4.7 KiB
Markdown
122 lines
4.7 KiB
Markdown
# Flash — Agent Guidelines
|
|
|
|
This document defines the conventions and rules that all agents (AI or human) must follow
|
|
when working on this repository. Read it entirely before making any change.
|
|
|
|
---
|
|
|
|
## Git Workflow
|
|
|
|
### Branch Naming
|
|
|
|
| Type | Pattern | Example |
|
|
|------|---------|---------|
|
|
| New feature | `feature/<scope>/<short-description>` | `feature/ext-oidc/pkce-support` |
|
|
| Bug fix | `fix/<scope>/<short-description>` | `fix/core/router-npe` |
|
|
| Hotfix on released version | `hotfix/<version>/<short-description>` | `hotfix/2.0.1/auth-bypass` |
|
|
| CI/infra changes | `feature/ci/<short-description>` | `feature/ci/add-snapshot-workflow` |
|
|
|
|
Rules:
|
|
- Always branch from `master`.
|
|
- Branch names are lowercase, words separated by `-`.
|
|
- Never push directly to `master`.
|
|
- Never create `develop`, `release/*`, or any other long-lived branch.
|
|
|
|
### Commit Messages — Conventional Commits
|
|
|
|
Format: `<type>(<scope>): <short description>`
|
|
|
|
| Type | When to use |
|
|
|------|-------------|
|
|
| `feat` | New feature |
|
|
| `fix` | Bug fix |
|
|
| `refactor` | Code change without feature/fix |
|
|
| `test` | Adding or updating tests |
|
|
| `docs` | Documentation only |
|
|
| `chore` | Build, deps, tooling — no production code |
|
|
| `ci` | Changes to GitHub Actions workflows |
|
|
|
|
Allowed scopes: `core`, `testing`, `ext-jackson`, `ext-openapi`, `ext-oidc`, `ext-routeviewer`,
|
|
`ext-view-core`, `ext-view-jte`, `ext-view-thymeleaf`, `ext-limiter`, `ext-web-bundler`,
|
|
`ext-mcp`, `ext-data-core`, `ext-data-jdbc`, `ext-data-hibernate`, `release`, `deps`, `ci`.
|
|
|
|
Examples:
|
|
```
|
|
feat(ext-oidc): add PKCE support
|
|
fix(core): fix NPE in RouteHandler when path is null
|
|
chore(deps): upgrade jackson to 2.18.0
|
|
ci: add timeout to snapshot workflow
|
|
chore(release): 2.1.0
|
|
```
|
|
|
|
### Pull Requests
|
|
|
|
- Every branch must be merged via PR, never with a direct push.
|
|
- PR title must follow Conventional Commits format.
|
|
- CI (`ci.yml`) must be green before merging.
|
|
- Squash merge is preferred for `feature/*` and `fix/*` to keep history clean.
|
|
- Merge commit is preferred for hotfixes (preserves the fix commit intact).
|
|
|
|
---
|
|
|
|
## Versioning
|
|
|
|
- All modules share a single version defined in the root `pom.xml` (`flash-parent`).
|
|
- Never change the version in child POMs — always and only in the parent.
|
|
- Current scheme: `MAJOR.MINOR.PATCH`
|
|
- MAJOR: breaking API changes
|
|
- MINOR: new backward-compatible features
|
|
- PATCH: backward-compatible bug fixes on an already-released version
|
|
- During development, master always carries a `-SNAPSHOT` version.
|
|
- **Never manually edit the version** — versions are bumped exclusively by the
|
|
`prepare-release` GitHub Actions workflow.
|
|
|
|
### Release Process (for maintainers only)
|
|
|
|
1. Ensure `master` is green (CI passing).
|
|
2. Go to GitHub Actions → `Prepare Release` → `Run workflow`.
|
|
3. Input `version` (e.g. `2.1.0`) and `next_version` (e.g. `2.2.0`).
|
|
4. The workflow handles everything: bump, commit, tag, push.
|
|
5. The `release` workflow then triggers automatically on the tag.
|
|
|
|
---
|
|
|
|
## Maven & Module Structure
|
|
|
|
- Root POM: `flash-parent` — defines all dependency versions and plugin config.
|
|
- `flash` module: the core framework JAR.
|
|
- `flash-testing` module: JUnit 5 harness for testing Flash applications. Deliberately not
|
|
under `flash-extensions/` — it is not something you `install()`, and it carries
|
|
`junit-jupiter-api` at compile scope.
|
|
- `flash-extensions` POM: aggregator for all extension modules.
|
|
- Extensions live under `flash-extensions/flash-ext-*/`.
|
|
- When adding a new extension:
|
|
1. Add the module to `flash-extensions/pom.xml` `<modules>`.
|
|
2. Add the dependency to `flash-extensions/pom.xml` `<dependencyManagement>`.
|
|
3. Add the dependency to the root `pom.xml` `<dependencyManagement>`.
|
|
4. Do **not** declare a `<version>` in the new module's POM — it inherits from the parent.
|
|
|
|
---
|
|
|
|
## CI/CD Pipelines
|
|
|
|
| Workflow | Trigger | What it does |
|
|
|----------|---------|--------------|
|
|
| `ci.yml` | Push to any branch, PR to master | Compile + test — required gate |
|
|
| `snapshot.yml` | Push to `master` | Deploy `-SNAPSHOT` to `maven.relism.dev/snapshots` |
|
|
| `prepare-release.yml` | Manual `workflow_dispatch` | Bump version, commit, tag, push |
|
|
| `release.yml` | Push of tag `v*` | GPG sign, deploy to `/releases`, JavaDoc to GitHub Pages, GitHub Release |
|
|
|
|
**Agents must never manually trigger `prepare-release` or modify version strings.**
|
|
|
|
---
|
|
|
|
## What Agents Must NOT Do
|
|
|
|
- Push directly to `master` or `gh-pages`.
|
|
- Manually edit `<version>` tags in any POM.
|
|
- Add new `<repositories>` or `<distributionManagement>` entries without explicit instruction.
|
|
- Modify `.github/workflows/*.yml` files without explicit instruction.
|
|
- Commit generated files (`target/`, `*.class`, `*.versionsBackup`).
|
|
- Use `git push --force` on any branch.
|