From b124e625bb1723895a443f41ed6e37f5ebf0dea5 Mon Sep 17 00:00:00 2001 From: JoseEstevez520 Date: Wed, 2 Sep 2026 13:30:14 +0200 Subject: [PATCH] docs: define branching and release workflow --- AGENTS.md | 11 ++++++++--- CONTRIBUTING.md | 29 ++++++++++++++++++++++++++++- 2 files changed, 36 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index cdec43c8..f203ecfb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -149,10 +149,15 @@ Two things are deliberately not: ## Git workflow -- Branch from `main` +- `main` is the latest public release and must remain deployable +- `develop` integrates the next version +- Branch normal work from `develop` using `feat/`, `fix/`, `docs/`, `refactor/`, `test/` or `chore/` +- Open normal pull requests into `develop` +- When a version is ready, open a pull request from `develop` into `main`, then tag and release it +- Branch urgent public fixes from `main` as `hotfix/description`, merge them into `main`, publish a + patch version and bring the correction back into `develop` - Commit format: `type: description` (types: feat, fix, docs, refactor, test, chore) -- PR into `main` -- No force push to `main` +- Do not push or force push directly to `main` ## Boundaries diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index aa0deb30..53a1d075 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -29,6 +29,33 @@ pnpm --dir apps/skillnet-web dev # http://localhost:5173, hot reload Open **5173**, not 3000. Vite proxies `/api` to the dockerized API. Rebuild the `web` container only to check the real production bundle. +## Branching and releases + +`main` represents the latest public release and must remain deployable. Normal development is +integrated in `develop` before it reaches `main`. + +For regular work, branch from `develop` and open a pull request back into `develop`. Use a name that +describes the change: + +* `feat/course-quality-evaluation` +* `fix/course-generation-timeout` +* `docs/deployment-guide` +* `refactor/media-pipeline` +* `test/dynamic-course-delivery` +* `chore/dependency-update` + +Keep each branch focused and short lived. A roadmap theme is not a branch: split it into changes that +can be reviewed and merged independently. + +When `develop` contains a coherent, tested version, open a pull request from `develop` into `main`. +After it is merged, create the version tag and GitHub Release from `main`. + +An urgent correction to the public version is the exception. Branch `hotfix/description` from +`main`, open the pull request into `main`, publish a patch version, then bring the same correction +back into `develop`. + +Do not push or force push directly to `main`. + ## Before you open a pull request Run what CI runs. Neither command needs a database or an API key: @@ -55,7 +82,7 @@ to a 384 column. Re-run the seed afterwards. boundaries of what not to touch. The short version: - Commit format: `type: description` — `feat`, `fix`, `docs`, `refactor`, `test`, `chore`. -- Branch from `main`, PR into `main`, no force push to `main`. +- Follow the branching and release flow above. Normal pull requests target `develop`. - TypeScript on the frontend, Python on the backend. Ruff for Python, Prettier for TS. - All LLM calls go through litellm. Never hardcode a provider. - Tailwind utilities and the tokens in `docs/design/design-system.md`. No inline styles.