nessar/vac-optimizer
1
0 Fork 0
Code Issues 7 Pull Requests 4 Actions 1 Packages Projects 1 Releases Wiki Activity

docs: migrate repository guidance to Gitea

Browse Source
This commit is contained in:
nessar committed 2026-10-13 19:38:32 +02:00
1 parent 0d900fd72d
commit 7d60157863
31 files changed
+180 -102
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+26 -16
View File
@@ -2,6 +2,8 @@
VacOptimizer is a personal leave planner for turning dated leave balances into a deterministic plan around weekends and French public holidays. It handles mandatory rules, ordered preferences, earned leave, expiring balances, and interrupted calculations without relying on a backend solver.
Source code, issues, and pull requests are hosted on [Gitea](https://gitea.nessar.fr/nessar/vac-optimizer). The [issue-tracker guide](docs/agents/issue-tracker.md) documents `tea-cli` access and tracker conventions.
The planner answers these questions:
- Is the request valid?
@@ -164,7 +166,7 @@ The trace explorer navigates original phases and atomic decisions, expands candi
- Vitest through the Angular test builder
- ESLint and Prettier
- Angular server build hosted by Express
- GitLab CI and a multi-stage Docker image
- Gitea repository hosting and a multi-stage Docker image
The `/benchmark` route and planner core are lazy-loaded, so the normal application does not execute the benchmark or bundle the planner core into its main entry point.
@@ -236,37 +238,43 @@ The image builds the Angular application with Bun and Node, then runs the genera
## Continuous integration
GitLab CI runs independent validation, test, build, security, and image stages:
CI execution is frozen after the migration to Gitea, and Gitea Actions is disabled. [Issue #268](https://gitea.nessar.fr/nessar/vac-optimizer/issues/268) tracks conversion of the preserved CI configuration to Gitea Actions. There is no checked-in `.gitea/workflows/` workflow yet.
The preserved `.gitlab-ci.yml` defines validation, test, build, security, and image stages:
- ESLint, Prettier, and TypeScript checks;
- Vitest with coverage artifacts;
- an optimized production build;
- GitLab SAST and Trivy filesystem scanning;
- legacy GitLab SAST and Trivy filesystem scanning;
- GitFlow, Conventional Commit, and release-version checks;
- Docker image publication for every successful branch push, including branches with an open MR.
- Docker image publication for successful branch pushes and same-project reviews.
Pipelines switch to MR pipelines when a branch has an open MR, avoiding duplicate builds. Docker publication from MR pipelines is limited to detached pipelines within this project. Tag pipelines promote the already-built commit image instead of rebuilding it.
These definitions are migration inputs; they do not execute on Gitea. The policy script also still expects GitLab `CI_*` variables. Triggers, required checks, runner requirements, secrets, security scanning, image publication, and merge-message templates must be reviewed as part of #268 before the owner enables the converted workflow. Historical CI logs, reports, and downloadable artifacts were not imported; administrator rollback backups retain them.
The required `test` job runs application tests with coverage, one worker and a 2 GiB Node heap limit. A separate automatic `benchmark` job uses the same environment outside coverage instrumentation, with the unchanged five-minute timeout and protocol assertions.
In the preserved configuration, the required `test` job runs application tests with coverage, one worker and a 2 GiB Node heap limit. A separate `benchmark` job uses the same environment outside coverage instrumentation, with the unchanged five-minute timeout and protocol assertions.
At the user's request, the benchmark job has `allow_failure: true` while #78 is open, so benchmark failure does not block functional delivery. #78 must restore the required benchmark gate after the protocol passes. A green pipeline during this exception does not establish benchmark acceptance.
At the user's request, the preserved benchmark job has `allow_failure: true` while [#78](https://gitea.nessar.fr/nessar/vac-optimizer/issues/78) is open. Carry that advisory status into the converted workflow; #78 must restore the required benchmark gate after the protocol passes. Passing functional checks during this exception does not establish benchmark acceptance.
Both protected branches require the unsatisfied status `gitlab-to-gitea/ci-conversion-required` until conversion is reviewed. Local validation does not satisfy this status; owner review and replacement of the migration gate are required before merges resume. See #268 for the migration requirements.
### GitFlow and releases
`develop` is the default integration branch. Create `feature/*` branches from it, rebase them onto the current `origin/develop` before opening or merging their MR, and merge into `develop` with a merge commit (`--no-ff`). Existing working-branch names such as `feat/*` follow the same rules. Working branches cannot merge `develop` into themselves instead of rebasing.
`develop` is the default integration branch. Create `feature/*` branches from it, rebase them onto the current `origin/develop` before opening or merging their PR, and merge into `develop` with a merge commit (`--no-ff`). Existing working-branch names such as `feat/*` follow the same rules. Working branches cannot merge `develop` into themselves instead of rebasing.
Create `release/X.Y.Z` from `develop` when the release scope is ready. Set `package.json` to `X.Y.Z` on this branch, stabilize it, then merge it into `main` and back into `develop`. Keep the release branch until both MRs have merged. A `hotfix/X.Y.Z` starts from `main`, changes the package version, and follows the same two-target merge process. Do not rebase `main`, `develop`, or a frozen release onto ongoing development.
Create `release/X.Y.Z` from `develop` when the release scope is ready. Set `package.json` to `X.Y.Z` on this branch, stabilize it, then merge it into `main` and back into `develop`. Keep the release branch until both PRs have merged. A `hotfix/X.Y.Z` starts from `main`, changes the package version, and follows the same two-target merge process. Do not rebase `main`, `develop`, or a frozen release onto ongoing development.
Use Conventional Commits for new commits and MR titles, for example `feat(calendar): add planning periods`, `fix(planner): handle expired balances`, or `chore(release): prepare 1.6.0`. Scopes are optional; `!` marks a breaking change. GitLab generates merge messages from the validated MR title. Legacy history is not rewritten.
Use Conventional Commits for new commits and PR titles, for example `feat(calendar): add planning periods`, `fix(planner): handle expired balances`, or `chore(release): prepare 1.6.0`. Scopes are optional; `!` marks a breaking change. The merge commit subject must preserve the validated PR title. Gitea supports a [Git-based merge-message template](https://docs.gitea.com/usage/issues-prs/merge-message-templates/) at `.gitea/default_merge_message/MERGE_TEMPLATE.md`, using `${PullRequestTitle}` and `${PullRequestReference}`. Its introduction and an example expanded message are part of #268; legacy history is not rewritten.
The image tag contract to preserve during CI conversion is:
| Trigger | Published image tags |
| --- | --- |
| Successful push to any branch | `branch-<GitLab ref slug>` and `sha-<full commit SHA>` |
| Successful push to any branch | `branch-<normalized branch slug>` and `sha-<full commit SHA>` |
| Explicit release tag `vX.Y.Z` | `vX.Y.Z` and `latest`, using the existing SHA image |
For example, `feature/calendar` publishes `branch-feature-calendar`; integration publishes `branch-develop`. GitLab normalizes ref slugs to lowercase and truncates them to 63 bytes, so choose branch names with distinct slugs. Only valid release tags can update `latest`.
For example, `feature/calendar` uses `branch-feature-calendar`; integration uses `branch-develop`. Preserve the previous slug normalization: lowercase the branch name, replace characters other than `a-z` and `0-9` with `-`, truncate to 63 bytes, and remove leading/trailing `-`. Choose branch names with distinct slugs. Only valid release tags can update `latest`. Automatic image publication and tag promotion remain frozen until #268 is complete.
After the MR into `main` and its full pipeline have succeeded, tag the published main commit:
After CI conversion is complete, the PR into `main` has merged, and its full checks and SHA image publication have succeeded, tag the published main commit:
```bash
git fetch origin
@@ -274,11 +282,13 @@ git tag -a v1.6.0 origin/main -m "Release 1.6.0"
git push origin v1.6.0
```
The tag must match the checked-out `package.json` version, use stable `vMAJOR.MINOR.PATCH` syntax, and point to a commit reachable from `main`. Wait for the main pipeline before tagging: the release job requires its `sha-<commit>` image. Tags do not increment the version automatically.
The tag must match the tagged commit's `package.json` version, use stable `vMAJOR.MINOR.PATCH` syntax, and point to a commit reachable from `main`. Wait for the main checks and image publication before tagging: promotion requires its `sha-<commit>` image. Tags do not increment the version automatically.
GitLab project settings must use `develop` as the default branch, the **Merge commit** method, squashing disabled, and **Pipelines must succeed** with skipped pipelines disallowed. Protect `main` and `develop` with no direct or forced pushes and Maintainer-only merges. Set the merge commit template to `%{title}` followed by the MR reference, preserving Conventional Commit subjects. The CI permits only `release/*` and `hotfix/*` into `main`; working MRs target `develop`. Rebase checks validate the target head at pipeline time: if `develop` advances afterward, rebase and rerun the MR pipeline before merging.
The Gitea repository policy requires `develop` as the default branch and **Merge commit** as the merge method, with squash and rebase merge methods disabled. Configure [branch protection](https://docs.gitea.com/usage/access-control/protected-branches/) for `main` and `develop` to disable direct and forced pushes, restrict the merge allowlist to designated maintainers, require successful status checks, and block outdated PRs. Administrators must follow the protection rules. Replace the migration gate with the reviewed check contexts only after #268 is complete. These are required settings; the migration does not establish that every setting has already been applied.
Run the policy integration check locally with `node scripts/ci-policy.test.mjs`.
Only `release/*` and `hotfix/*` PRs may target `main`; working PRs target `develop`. The converted CI must retain these rules and the rebase checks. If `develop` advances after validation, rebase and rerun the PR checks before merging.
Run the preserved policy integration check locally with `node scripts/ci-policy.test.mjs`. It verifies the legacy policy adapter; it does not validate a Gitea workflow or satisfy the migration gate.
## Domain and design references