ci: setup CI/CD pipelines, versioning and agent guidelines
This commit is contained in:
Relism
@@ -0,0 +1,118 @@
|
||||
# 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`, `ext-jackson`, `ext-openapi`, `ext-oidc`, `ext-routeviewer`,
|
||||
`ext-view-core`, `ext-view-jte`, `ext-view-thymeleaf`, `ext-limiter`, `ext-web-bundler`,
|
||||
`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-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.
|
||||
Reference in New Issue
Block a user