diff --git a/.github/workflows/deploy-landing.yml b/.github/workflows/deploy-landing.yml index fd36709..855b5fa 100644 --- a/.github/workflows/deploy-landing.yml +++ b/.github/workflows/deploy-landing.yml @@ -3,13 +3,13 @@ name: Deploy landing # Build the Nuxt landing and publish the compiled static site to a branch that # holds only the build output: # - push to main → pages/landing (production) -# - push to dev → pages/landing-dev (staging, to preview before main) +# - push to develop → pages/landing-dev (staging, to preview before main) on: push: - branches: [main, dev] + branches: [main, develop] workflow_dispatch: -# One deploy per source branch at a time; don't let main and dev cancel each other. +# One deploy per source branch at a time; don't let main and develop cancel each other. concurrency: group: deploy-landing-${{ github.ref_name }} cancel-in-progress: true @@ -39,7 +39,9 @@ jobs: env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | - # main goes to production; every other branch (dev) goes to staging. + # main goes to production; every other branch (develop) goes to staging. + # The target branch keeps its -dev name: it is what serves the staging + # site, and renaming it would change that URL for no gain. if [ "$GITHUB_REF_NAME" = "main" ]; then TARGET="pages/landing" else diff --git a/.github/workflows/gitflow.yml b/.github/workflows/gitflow.yml index 2d21507..49734b3 100644 --- a/.github/workflows/gitflow.yml +++ b/.github/workflows/gitflow.yml @@ -1,19 +1,19 @@ name: Gitflow # Enforce where changes come from: -# - PRs into dev must come from a gitflow branch (feature/*, hotfix/* or +# - PRs into develop must come from a gitflow branch (feature/*, hotfix/* or # release/*), or from main itself (a post-release back-merge). -# - PRs into main are releases and must come from dev, only. +# - PRs into main are releases and must come from develop, only. # Both checks are required by the branch rulesets, so a PR from any other # source branch cannot be merged. on: pull_request: - branches: [dev, main] + branches: [develop, main] jobs: branch-name: name: gitflow branch name - if: github.base_ref == 'dev' + if: github.base_ref == 'develop' runs-on: ubuntu-latest steps: - name: Check the head branch follows gitflow @@ -24,7 +24,7 @@ jobs: feature/*|hotfix/*|release/*|main) echo "ok: $HEAD_REF" ;; *) - echo "PRs into dev must come from a feature/*, hotfix/* or release/* branch (got: $HEAD_REF)" + echo "PRs into develop must come from a feature/*, hotfix/* or release/* branch (got: $HEAD_REF)" exit 1 ;; esac @@ -33,13 +33,13 @@ jobs: if: github.base_ref == 'main' runs-on: ubuntu-latest steps: - - name: Check the release comes from dev + - name: Check the release comes from develop env: HEAD_REF: ${{ github.head_ref }} run: | - if [ "$HEAD_REF" = "dev" ]; then - echo "ok: release PR from dev" + if [ "$HEAD_REF" = "develop" ]; then + echo "ok: release PR from develop" else - echo "PRs into main are releases and must come from dev (got: $HEAD_REF)" + echo "PRs into main are releases and must come from develop (got: $HEAD_REF)" exit 1 fi diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index f6eb7d3..fb99cd9 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -30,7 +30,7 @@ concurrency: jobs: # A release must correspond to a released state of the code: refuse any # v* tag whose commit is not part of main's history (e.g. a tag placed on - # dev by mistake). The publish job requires this to pass. + # develop by mistake). The publish job requires this to pass. verify: name: tag is on main if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/') diff --git a/.github/workflows/test-and-build.yml b/.github/workflows/test-and-build.yml index 5f02cab..b2e92af 100644 --- a/.github/workflows/test-and-build.yml +++ b/.github/workflows/test-and-build.yml @@ -5,7 +5,7 @@ name: test-and-build # landing has no test suite and is built by deploy-landing.yml instead. on: push: - branches: [main, dev] + branches: [main, develop] # `labeled` is not in the default set, and without it the `full-matrix` label # below would be a documented escape hatch that never fires: adding a label # would change nothing until the next push. @@ -245,11 +245,11 @@ jobs: # times a Linux one in billed minutes and feature work does not need them. # # They run when the code is on, or heading to, a shipping branch: - # - any push to dev or main (the `on:` block already limits pushes to those) - # - a pull request FROM dev (the release PR into main), from main (a + # - any push to develop or main (the `on:` block already limits pushes to those) + # - a pull request FROM develop (the release PR into main), from main (a # back-merge) or from a release/* branch # A pull request from feature/* or hotfix/* therefore stays Linux only, and - # picks these up when it lands on dev. When such a branch does touch + # picks these up when it lands on develop. When such a branch does touch # platform-specific code, label the pull request `full-matrix` to ask for # them anyway rather than renaming the branch. # @@ -263,7 +263,7 @@ jobs: if: >- github.event_name == 'push' || github.event_name == 'workflow_dispatch' || - github.head_ref == 'dev' || + github.head_ref == 'develop' || github.head_ref == 'main' || startsWith(github.head_ref, 'release/') || contains(github.event.pull_request.labels.*.name, 'full-matrix') @@ -534,22 +534,22 @@ jobs: run: make desktop/compile # The same compile on the other two platforms it ships to, on the release - # path only: a release/* branch, and the dev to main pull request itself. + # path only: a release/* branch, and the develop to main pull request itself. # # That second one is not optional. The pull request into main IS the release # gate, the last thing that runs before a tag exists, so a desktop build # skipping there would mean the app was never compiled for macOS or Windows - # on the commit about to ship. Its head branch is dev, not release/*, so it + # on the commit about to ship. Its head branch is develop, not release/*, so it # needs naming separately. # - # Not on dev, deliberately. The test jobs above already compile this crate on + # Not on develop, deliberately. The test jobs above already compile this crate on # both platforms: `make desktop/test-rust` runs `cargo test` inside src-tauri, # which goes through generate_context!(), runs build.rs (so rc.exe, the icon # and the manifest on Windows) and links executables. All this adds is the # release profile, which for this crate means lto, codegen-units = 1 and # panic = "abort": a real difference, but a narrow one, and the slowest kind # of build there is. Paying ten to fifteen minutes per platform on every push - # to dev for that is not a good trade. + # to develop for that is not a good trade. # # On a release branch it is, because the alternative is finding out after the # tag is pushed. Note what it still does not cover: it compiles rather than diff --git a/README.md b/README.md index 999fccf..79720cb 100644 --- a/README.md +++ b/README.md @@ -254,9 +254,9 @@ make fmt make lint # format / clippy both Rust workspaces make fmt/check # fail instead of reformatting (the tree is rustfmt clean) ``` -Work happens on `dev`, merged into `main` per release (see +Work happens on `develop`, merged into `main` per release (see [git flow](docs/git_flow.md)). CI invokes these same `make` targets on every -pull request and on pushes to `dev` and `main`. +pull request and on pushes to `develop` and `main`. ## License diff --git a/docs/architecture.md b/docs/architecture.md index 363f6b1..d15f712 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -550,7 +550,7 @@ outside. Source files carry no inline `#[cfg(test)] mod tests`. ## CI -`.github/workflows/test-and-build.yml` runs on every push to `main`/`dev` and +`.github/workflows/test-and-build.yml` runs on every push to `main`/`develop` and on pull requests, entirely on Linux runners. Every job is named `test ()` or `build ()`, so a check's name says what it does and which app it belongs to; the job ids match those names (`test-cli`, @@ -569,10 +569,10 @@ and is the only Linux job that compiles the Tauri crate at all), while `test (server-frontend)` is independent of the Rust engine and waits only on `fmt`. **Linux runs everything, on every push and every pull request.** macOS and Windows run the whole Rust suite too, as `test (rust, macos)` and -`test (rust, windows)`, but only for the branches that ship: any push to `dev` -or `main`, and any pull request from `dev`, from `main`, or from a `release/*` +`test (rust, windows)`, but only for the branches that ship: any push to `develop` +or `main`, and any pull request from `develop`, from `main`, or from a `release/*` branch. A `feature/*` or `hotfix/*` pull request stays Linux only and picks -them up when it lands on `dev`, because those runners cost several times a +them up when it lands on `develop`, because those runners cost several times a Linux one per minute. When such a branch does touch platform-specific code, labelling the pull request `full-matrix` asks for them anyway. @@ -585,13 +585,13 @@ a developer's own machine ever ran the desktop suite there. The desktop app is compiled on Linux everywhere as `build (desktop)`, and on the other two platforms as `build (desktop, macos)` and `build (desktop, -windows)` **on the release path only**: a `release/*` branch, and the `dev` to +windows)` **on the release path only**: a `release/*` branch, and the `develop` to `main` pull request itself. That second one matters, since that pull request is -the release gate and its head branch is `dev` rather than `release/*`, so +the release gate and its head branch is `develop` rather than `release/*`, so skipping there would mean the app was never compiled for macOS or Windows on the commit about to ship. -Not on `dev`, deliberately. The cross-platform test jobs already compile this +Not on `develop`, deliberately. The cross-platform test jobs already compile this crate on both platforms, since `make desktop/test-rust` runs `cargo test` inside `src-tauri`, which goes through `generate_context!()`, runs `build.rs` and links executables. All the extra build adds is the release profile (`lto`, diff --git a/docs/deployment.md b/docs/deployment.md index a9310e0..4971476 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -13,23 +13,28 @@ pipeline and [desktop.md](desktop.md) for the desktop bundle specifics. The landing is published to a **build branch** that holds only the compiled site (no source). Which branch depends on where the change landed: -| Source branch | Deploys to | Environment | Purpose | -|---------------|----------------------|-------------|-------------------------------------------| -| `dev` | `pages/landing-dev` | staging | preview changes before they reach `main` | -| `main` | `pages/landing` | production | the live site | +| Source branch | Deploys to | Environment | Purpose | +|---------------|---------------------|-------------|------------------------------------------| +| `develop` | `pages/landing-dev` | staging | preview changes before they reach `main` | +| `main` | `pages/landing` | production | the live site | -So the normal flow is: iterate on `dev` → check the result on `pages/landing-dev` -→ merge `dev` into `main` (a release) → production updates on `pages/landing`. +The staging branch keeps its `-dev` name now that the source branch is +`develop`. It is the branch that serves the staging site, so renaming it would +change that URL and buy nothing; the name is a label for the environment rather +than for the branch it is built from. + +So the normal flow is: iterate on `develop` → check the result on `pages/landing-dev` +→ merge `develop` into `main` (a release) → production updates on `pages/landing`. ``` -commit to dev ──▶ CI build ──▶ pages/landing-dev (staging) -merge to main ──▶ CI build ──▶ pages/landing (production) +commit to develop ──▶ CI build ──▶ pages/landing-dev (staging) +merge to main ──▶ CI build ──▶ pages/landing (production) ``` ## How it works The workflow is [`.github/workflows/deploy-landing.yml`](../.github/workflows/deploy-landing.yml). -On every push to `main` or `dev` (and via manual **Run workflow** / `workflow_dispatch`): +On every push to `main` or `develop` (and via manual **Run workflow** / `workflow_dispatch`): 1. **Build** — `make landing/build`, which runs `npm ci` then `nuxt generate`, producing the static site in `apps/landing/.output/public`. @@ -39,7 +44,7 @@ On every push to `main` or `dev` (and via manual **Run workflow** / `workflow_di branch: `main` → `pages/landing`, anything else → `pages/landing-dev`. The deploy commit is authored as the repo owner (via the account's GitHub noreply -email), not a bot. Concurrency is keyed per source branch, so a `dev` deploy and a +email), not a bot. Concurrency is keyed per source branch, so a `develop` deploy and a `main` deploy never cancel each other. Because each deploy force-pushes an orphan-style commit, the build branches never diff --git a/docs/git_flow.md b/docs/git_flow.md index 01686ee..d765b74 100644 --- a/docs/git_flow.md +++ b/docs/git_flow.md @@ -7,15 +7,15 @@ This repository follows a **gitflow** branching model, kept deliberately simple. Where humans commit code: - **`main`** — released versions only. Every merge into `main` marks a version and gets a tag (`vX.Y.Z`). Changes arrive only through pull requests (see [Branch protections](#branch-protections)). -- **`dev`** — the integration branch where real day-to-day work happens. All work lands here first, always through a pull request from a gitflow branch; direct pushes are blocked. -- **`feature/`** — branched off `dev` for each unit of work, merged back into `dev` via pull request when done. Since direct pushes to `dev` are blocked, even small changes travel on a short-lived feature branch. +- **`develop`** — the integration branch where real day-to-day work happens. All work lands here first, always through a pull request from a gitflow branch; direct pushes are blocked. +- **`feature/`** — branched off `develop` for each unit of work, merged back into `develop` via pull request when done. Since direct pushes to `develop` are blocked, even small changes travel on a short-lived feature branch. - **`release/`** — the version bump and any last touches before a - release, branched off `dev` and merged back into `dev` by pull request, after - which `dev` goes to `main` as usual. Mechanically a feature branch; the name + release, branched off `develop` and merged back into `develop` by pull request, after + which `develop` goes to `main` as usual. Mechanically a feature branch; the name is what makes CI run the macOS and Windows suites on it, which is the point of using it for a release rather than `feature/release-`. -- **`hotfix/`** — an urgent fix for a released version. Mechanically a feature branch (off `dev`, merged into `dev` by PR); the name signals urgency, and a release (`dev` → `main`, new patch version + tag) follows immediately. PRs into `main` accept only `dev`, so there is no direct fix-to-main path; keep `dev` releasable. +- **`hotfix/`** — an urgent fix for a released version. Mechanically a feature branch (off `develop`, merged into `develop` by PR); the name signals urgency, and a release (`develop` → `main`, new patch version + tag) follows immediately. PRs into `main` accept only `develop`, so there is no direct fix-to-main path; keep `develop` releasable. ## Deploy branches (auto-generated — never commit by hand) @@ -23,7 +23,10 @@ CI force-pushes the built landing site to these branches; they contain only buil output (no source), and each deploy replaces the branch wholesale: - **`pages/landing`** — the **production** landing build, published from `main`. -- **`pages/landing-dev`** — the **staging** landing build, published from `dev`, to preview changes before they reach production. +- **`pages/landing-dev`** — the **staging** landing build, published from + `develop`, to preview changes before they reach production. It keeps its + `-dev` name: it is what serves the staging site, and the name describes the + environment rather than the branch the build came from. A ruleset blocks deleting these branches; not pushing to them by hand is a convention (see [Branch protections](#branch-protections)). @@ -39,8 +42,8 @@ bind everyone, including the repo owner: (0 required approvals, solo maintainer); force pushes and deletion are blocked. The required **release source branch** status check ([`gitflow.yml`](../.github/workflows/gitflow.yml)) fails any PR whose head - branch is not `dev`: releasing from `dev` is the only way into `main`. -- **`protect-dev`**: the same for `dev`, plus the required **gitflow branch + branch is not `develop`: releasing from `develop` is the only way into `main`. +- **`protect-develop`**: the same for `develop`, plus the required **gitflow branch name** status check ([`gitflow.yml`](../.github/workflows/gitflow.yml)), which fails any PR whose head branch is not `feature/*`, `hotfix/*`, `release/*`, or @@ -54,9 +57,9 @@ bind everyone, including the repo owner: ## Releasing -When `dev` reaches a state worth shipping, open a pull request from `dev` into `main`, merge it, and tag the merge commit with the version number. `main` therefore only ever moves forward one version at a time. +When `develop` reaches a state worth shipping, open a pull request from `develop` into `main`, merge it, and tag the merge commit with the version number. `main` therefore only ever moves forward one version at a time. -Pushing the tag triggers [`release.yml`](../.github/workflows/release.yml), which builds the CLI binaries (macOS arm64 and Intel tarballs) and the desktop app (one universal macOS `.dmg`, `.deb`/`.rpm`/`.AppImage` builds for x86_64 Linux, and an `.msi` plus NSIS setup `.exe` for x64 Windows), all unsigned for now, and publishes a GitHub release with them, their sha256 checksums, and auto-generated notes. The build also runs the Rust test suite once on the macOS runner — the one shipped OS regular CI never exercises, since CI is Linux-only — so a macOS-only test failure blocks the release. Only exact `vX.Y.Z` tags trigger it, and a guard job refuses to publish when the tagged commit is not on `main` (a tag placed on `dev` by mistake never becomes a release) or when the tag does not match the versions in `apps/cli/Cargo.toml` and `apps/desktop/src-tauri/tauri.conf.json` — bump **both** before tagging, or the CLI would report the wrong `--version` and the desktop bundles (`.dmg`, `.deb`, `.rpm`, `.AppImage`, `.msi`, setup `.exe`) would carry the wrong version in their names. The `workflow_dispatch` trigger dry-runs the builds without publishing anything, even if pointed at a tag. +Pushing the tag triggers [`release.yml`](../.github/workflows/release.yml), which builds the CLI binaries (macOS arm64 and Intel tarballs) and the desktop app (one universal macOS `.dmg`, `.deb`/`.rpm`/`.AppImage` builds for x86_64 Linux, and an `.msi` plus NSIS setup `.exe` for x64 Windows), all unsigned for now, and publishes a GitHub release with them, their sha256 checksums, and auto-generated notes. The build also runs the Rust test suite once on the macOS runner — the one shipped OS regular CI never exercises, since CI is Linux-only — so a macOS-only test failure blocks the release. Only exact `vX.Y.Z` tags trigger it, and a guard job refuses to publish when the tagged commit is not on `main` (a tag placed on `develop` by mistake never becomes a release) or when the tag does not match the versions in `apps/cli/Cargo.toml` and `apps/desktop/src-tauri/tauri.conf.json` — bump **both** before tagging, or the CLI would report the wrong `--version` and the desktop bundles (`.dmg`, `.deb`, `.rpm`, `.AppImage`, `.msi`, setup `.exe`) would carry the wrong version in their names. The `workflow_dispatch` trigger dry-runs the builds without publishing anything, even if pointed at a tag. ## Commits @@ -64,5 +67,5 @@ We favor **small commits with few changes** over large ones: - One logical change per commit — a commit should be explainable in one sentence. - Prefer several small commits over one big commit, even within a single task. -- Red commits are fine on `feature/*`/`hotfix/*` branches while work is in progress (say so in the message); whatever merges into `dev` must pass `cargo test`, so every commit on `dev` and `main` is green. +- Red commits are fine on `feature/*`/`hotfix/*` branches while work is in progress (say so in the message); whatever merges into `develop` must pass `cargo test`, so every commit on `develop` and `main` is green. - Message format: a short imperative summary line, optionally prefixed by area (`core:`, `docs:`, `chore:`), with a body only when the *why* is not obvious from the diff.