diff --git a/.github/workflows/build-app.yml b/.github/workflows/build-app.yml new file mode 100644 index 000000000..8ef8897cc --- /dev/null +++ b/.github/workflows/build-app.yml @@ -0,0 +1,124 @@ +# Builds the application and its changelog, and uploads them as the +# `build-output` artifact. BUILD (develop) and RELEASE (PlaceOS releases) call +# this workflow, then publish the artifact to a build/* branch. +name: BUILD APP + +on: + workflow_call: + inputs: + ref: + description: 'Commit to build. Empty: the commit that started the run' + type: string + default: '' + configuration: + description: 'Angular build configuration: development or production' + type: string + required: true + tag: + description: 'Release tag to add to the commit before the build. The version info shows it' + type: string + default: '' + +permissions: + contents: read + +jobs: + build: + runs-on: ubuntu-latest + timeout-minutes: 3 + steps: + - uses: actions/checkout@v6 + with: + ref: ${{ inputs.ref }} + + # The changelog needs the history and tags of this commit only. + # fetch-depth: 0 also downloads the build/* deploy branches (about + # 560 MB against 30 MB). + - name: Fetch history and tags + env: + REF: ${{ inputs.ref || github.ref }} + run: git fetch --unshallow --tags origin "$REF" + + # Local only. config/version.js (git describe) and git-cliff read + # it. RELEASE pushes the tag after the deploy. --force: a retry of + # a release fetches the tag that the first run pushed. + - name: Tag the release + if: inputs.tag != '' + env: + TAG: ${{ inputs.tag }} + run: git tag --force "$TAG" + + - name: Setup Bun + uses: oven-sh/setup-bun@v2 + with: + bun-version: '1.3.11' + + - name: Install dependencies + run: bun install --frozen-lockfile + + - name: Setup version + run: bun run postinstall + + - name: Install git-cliff + uses: taiki-e/install-action@v2 + with: + tool: git-cliff@2.13.1 + + - name: Initialise Pipeline Chat Status + uses: fjogeleit/http-request-action@master + continue-on-error: true + with: + url: ${{ secrets.STATUS_URL }} + data: '{ "chat_url": "${{ secrets.CHAT_URL }}", "name": "${{ github.repository }}", "commit": "${{ github.sha }}", "pipeline_name": "backoffice", "branch": "${{ github.ref }}", "status": "processing", "url": "https://github.com/${{ github.repository }}/runs/${{ github.run_id }}" }' + + # Do not restore an Nx cache for this build. Nx does not hash the + # gitignored src/env/version.ts, so a cached build could deploy + # the version info of an earlier commit. + # git-cliff runs alongside the build; `wait` fails the step if it fails. + # Do not set GITHUB_REPO. cliff.toml uses no GitHub metadata, and + # the unauthenticated metadata requests hit the API rate limit. + - name: Build application and changelog + env: + CONFIGURATION: ${{ inputs.configuration }} + run: | + git-cliff --config cliff.toml --output "${RUNNER_TEMP}/CHANGELOG.md" & + cliff_pid=$! + bun run build -- --verbose --configuration="$CONFIGURATION" + wait "$cliff_pid" + + - name: Add application changelog to build + run: cp "${RUNNER_TEMP}/CHANGELOG.md" dist/backoffice/browser/CHANGELOG.md + + # Upload source maps so Sentry shows the original code. Skipped + # until the SENTRY_* secrets are set. Debug IDs change the scripts, + # so the service worker hashes are updated after. Development + # builds have no service worker. + # The release name must match SENTRY_RELEASE in src/app/common/sentry.ts. + - name: Upload source maps to Sentry + env: + SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }} + SENTRY_ORG: ${{ secrets.SENTRY_ORG }} + SENTRY_PROJECT: ${{ secrets.SENTRY_PROJECT }} + run: | + if [ -z "$SENTRY_AUTH_TOKEN" ] || [ -z "$SENTRY_ORG" ] || [ -z "$SENTRY_PROJECT" ]; then + echo "SENTRY_AUTH_TOKEN, SENTRY_ORG or SENTRY_PROJECT is not set. Skipping upload." + exit 0 + fi + release=$(bun -e "import { VERSION } from './src/env/version.ts'; console.log('backoffice@' + VERSION.hash)") + bunx sentry-cli sourcemaps inject dist/backoffice/browser + if [ -f dist/backoffice/browser/ngsw.json ]; then + bun config/ngsw-rehash.js dist/backoffice/browser + fi + bunx sentry-cli sourcemaps upload --release="$release" dist/backoffice/browser + + # Production builds make hidden source maps for Sentry only + - name: Remove hidden source maps + if: inputs.configuration != 'development' + run: find dist/backoffice/browser -name '*.map' -delete + + - name: Upload build artifact + uses: actions/upload-artifact@v4 + with: + name: build-output + path: dist/backoffice/browser + retention-days: 1 diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 25518f40c..7bce152ce 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -1,133 +1,30 @@ +# Builds develop and publishes it to build/dev. PlaceOS releases publish to +# build/prod through RELEASE (release.yml). See docs/releases.md. name: BUILD on: push: - branches: [develop, release/**, rc/**, release] + branches: [develop] + +permissions: + contents: read jobs: - # Run tests for all branches (runs in parallel with build) + # Tests run in parallel with the build. The dev deploy does not wait for them. test: uses: ./.github/workflows/test.yml - # Build job runs immediately without waiting for tests build: - runs-on: ubuntu-latest - timeout-minutes: 3 - outputs: - configuration: ${{ steps.build_ext.outputs.configuration }} - deploy_branch: ${{ steps.build_ext.outputs.deploy_branch }} - is_production: ${{ steps.build_ext.outputs.is_production }} - steps: - - uses: actions/checkout@v6 - - # The changelog needs the history and tags of this branch only. - # fetch-depth: 0 also downloads the build/* deploy branches (about - # 560 MB against 30 MB). - - name: Fetch branch history and tags - run: git fetch --unshallow --tags origin "$GITHUB_REF" - - - name: Setup Bun - uses: oven-sh/setup-bun@v2 - with: - bun-version: '1.3.11' - - - name: Install dependencies - run: bun install --frozen-lockfile - - - name: Setup version - run: bun run postinstall - - - name: Install git-cliff - uses: taiki-e/install-action@v2 - with: - tool: git-cliff@2.13.1 - - - name: Extract branch name - id: branch_name - shell: bash - run: echo "name=$(echo ${GITHUB_REF#refs/heads/} | sed 's/\//_/g')" >> $GITHUB_OUTPUT - - - name: Extract build configuration - shell: bash - id: build_ext - run: | - if [[ ${{ steps.branch_name.outputs.name }} == "release" ]] || [[ ${{ steps.branch_name.outputs.name }} == "release"* ]] || [[ ${{ steps.branch_name.outputs.name }} == "main" ]] - then - echo "configuration=production" >> $GITHUB_OUTPUT - echo "deploy_branch=prod" >> $GITHUB_OUTPUT - echo "is_production=true" >> $GITHUB_OUTPUT - elif [[ ${{ steps.branch_name.outputs.name }} == "rc"* ]] - then - echo "configuration=staging" >> $GITHUB_OUTPUT - echo "deploy_branch=uat" >> $GITHUB_OUTPUT - echo "is_production=true" >> $GITHUB_OUTPUT - else - echo "configuration=development" >> $GITHUB_OUTPUT - echo "deploy_branch=dev" >> $GITHUB_OUTPUT - echo "is_production=false" >> $GITHUB_OUTPUT - fi - - - name: Initialise Pipeline Chat Status - uses: fjogeleit/http-request-action@master - continue-on-error: true - with: - url: ${{ secrets.STATUS_URL }} - data: '{ "chat_url": "${{ secrets.CHAT_URL }}", "name": "${{ github.repository }}", "commit": "${{ github.sha }}", "pipeline_name": "backoffice", "branch": "${{ github.ref }}", "status": "processing", "url": "https://github.com/${{ github.repository }}/runs/${{ github.run_id }}" }' - - # Do not restore an Nx cache for this build. Nx does not hash the - # gitignored src/env/version.ts, so a cached build could deploy - # the version info of an earlier commit. - # git-cliff runs alongside the build; `wait` fails the step if it fails. - # Do not set GITHUB_REPO. cliff.toml uses no GitHub metadata, and - # the unauthenticated metadata requests hit the API rate limit. - - name: Build application and changelog - run: | - git-cliff --config cliff.toml --output "${RUNNER_TEMP}/CHANGELOG.md" & - cliff_pid=$! - bun run build -- --verbose --configuration=${{ steps.build_ext.outputs.configuration }} - wait "$cliff_pid" - - - name: Add application changelog to build - run: cp "${RUNNER_TEMP}/CHANGELOG.md" dist/backoffice/browser/CHANGELOG.md - - # Upload source maps so Sentry shows the original code. Skipped - # until the SENTRY_* secrets are set. Debug IDs change the scripts, - # so the service worker hashes are updated after. Development - # builds have no service worker. - # The release name must match SENTRY_RELEASE in src/app/common/sentry.ts. - - name: Upload source maps to Sentry - env: - SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }} - SENTRY_ORG: ${{ secrets.SENTRY_ORG }} - SENTRY_PROJECT: ${{ secrets.SENTRY_PROJECT }} - run: | - if [ -z "$SENTRY_AUTH_TOKEN" ] || [ -z "$SENTRY_ORG" ] || [ -z "$SENTRY_PROJECT" ]; then - echo "SENTRY_AUTH_TOKEN, SENTRY_ORG or SENTRY_PROJECT is not set. Skipping upload." - exit 0 - fi - release=$(bun -e "import { VERSION } from './src/env/version.ts'; console.log('backoffice@' + VERSION.hash)") - bunx sentry-cli sourcemaps inject dist/backoffice/browser - if [ -f dist/backoffice/browser/ngsw.json ]; then - bun config/ngsw-rehash.js dist/backoffice/browser - fi - bunx sentry-cli sourcemaps upload --release="$release" dist/backoffice/browser - - # Production builds make hidden source maps for Sentry only - - name: Remove hidden source maps - if: steps.build_ext.outputs.configuration != 'development' - run: find dist/backoffice/browser -name '*.map' -delete - - - name: Upload build artifact - uses: actions/upload-artifact@v4 - with: - name: build-output - path: dist/backoffice/browser - retention-days: 1 + uses: ./.github/workflows/build-app.yml + with: + configuration: development + secrets: inherit - # Deploy dev builds immediately after build (don't wait for tests) deploy-dev: needs: [build] - if: needs.build.outputs.is_production == 'false' + # Pushes to build/dev + permissions: + contents: write runs-on: ubuntu-latest timeout-minutes: 3 steps: @@ -149,7 +46,7 @@ jobs: uses: MrYuion/git-publish-subdir-action@develop env: REPO: self - BRANCH: build/${{ needs.build.outputs.deploy_branch }} + BRANCH: build/dev FOLDER: dist/backoffice/browser GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} MESSAGE: 'build(backoffice): [{sha}] CI build' @@ -161,41 +58,3 @@ jobs: url: ${{ secrets.STATUS_URL }} data: '{ "name": "${{ github.repository }}", "commit": "${{ github.sha }}", "pipeline_name": "backoffice", "branch": "${{ github.ref }}", "status": "${{ job.status }}", "url": "https://github.com/${{ github.repository }}/runs/${{ github.run_id }}" }' if: ${{ always() }} - - # Deploy production builds only after tests pass - deploy-production: - needs: [build, test] - if: needs.build.outputs.is_production == 'true' - runs-on: ubuntu-latest - timeout-minutes: 3 - steps: - - uses: actions/checkout@v6 - - - name: Download build artifact - uses: actions/download-artifact@v4 - with: - name: build-output - path: dist/backoffice/browser - - # Vercel reads vercel.json from the pushed commit. Build branches - # hold only the built files, so add one that turns off deployments. - - name: Turn off Vercel deployments for the build branch - run: | - echo '{ "git": { "deploymentEnabled": false } }' > dist/backoffice/browser/vercel.json - - - name: Deploy the application - uses: MrYuion/git-publish-subdir-action@develop - env: - REPO: self - BRANCH: build/${{ needs.build.outputs.deploy_branch }} - FOLDER: dist/backoffice/browser - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - MESSAGE: 'build(backoffice): CI build from {sha}' - - - name: Update Pipeline Chat Status - uses: fjogeleit/http-request-action@master - continue-on-error: true - with: - url: ${{ secrets.STATUS_URL }} - data: '{ "name": "${{ github.repository }}", "commit": "${{ github.sha }}", "pipeline_name": "backoffice", "branch": "${{ github.ref }}", "status": "${{ job.status }}", "url": "https://github.com/${{ github.repository }}/runs/${{ github.run_id }}" }' - if: ${{ always() }} diff --git a/.github/workflows/e2e-local.yml b/.github/workflows/e2e-local.yml index b4a746b0f..893abfc6d 100644 --- a/.github/workflows/e2e-local.yml +++ b/.github/workflows/e2e-local.yml @@ -16,10 +16,8 @@ on: workflow_dispatch: push: branches: - # The branches BUILD deploys from + # The branch BUILD deploys from - develop - - 'release/**' - - 'rc/**' # To work on this suite and this workflow - 'e2e/**' schedule: diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 000000000..fc6903af9 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,179 @@ +# Releases backoffice with each PlaceOS platform release. See docs/releases.md. +# +# The release ships the backoffice commit that the interfaces/backoffice +# submodule of PlaceOS/PlaceOS pins for that version. The workflow tags it +# v, tests it, builds it and publishes it to build/prod. PlaceOS +# installs load backoffice from build/prod. +name: RELEASE + +on: + # Sent by the "Tag and release" job of build.yml in PlaceOS/PlaceOS, with + # the payload { "version": "2.2611.6" } + repository_dispatch: + types: [placeos-release] + # To retry a release, or to roll back to an earlier version + workflow_dispatch: + inputs: + version: + description: 'PlaceOS version, for example 2.2611.6' + required: true + type: string + +permissions: + contents: write + +# One release at a time. A release that starts during a release waits. +concurrency: + group: release + cancel-in-progress: false + +jobs: + resolve: + runs-on: ubuntu-latest + timeout-minutes: 2 + outputs: + sha: ${{ steps.resolve.outputs.sha }} + tag: ${{ steps.resolve.outputs.tag }} + steps: + - name: Find the backoffice commit that the PlaceOS version pins + id: resolve + env: + GH_TOKEN: ${{ github.token }} + VERSION: ${{ github.event.client_payload.version || inputs.version }} + run: | + if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]{4}\.[0-9]+$ ]]; then + echo "::error::The version is not a PlaceOS release version, for example 2.2611.6" + exit 1 + fi + + sha="$(gh api "repos/PlaceOS/PlaceOS/contents/interfaces/backoffice?ref=${VERSION}" --jq .sha)" + if [[ ! "$sha" =~ ^[0-9a-f]{40}$ ]]; then + echo "::error::PlaceOS ${VERSION} does not pin a backoffice commit" + exit 1 + fi + + # Release only reviewed code. The cache scope of develop is + # shared, so a commit from a fork must not run here. + status="$(gh api "repos/${GITHUB_REPOSITORY}/compare/${sha}...develop" --jq .status)" + if [[ "$status" != "ahead" && "$status" != "identical" ]]; then + echo "::error::${sha} is not on develop" + exit 1 + fi + + # A retry can use the tag again. A tag on a different commit stops the release. + tag="v${VERSION}" + tagged="$(git ls-remote "https://github.com/${GITHUB_REPOSITORY}" "refs/tags/${tag}" | cut -f1)" + if [[ -n "$tagged" && "$tagged" != "$sha" ]]; then + echo "::error::${tag} is on ${tagged}. PlaceOS ${VERSION} pins ${sha}" + exit 1 + fi + + echo "Releasing ${sha} as ${tag}" + echo "sha=${sha}" >> "$GITHUB_OUTPUT" + echo "tag=${tag}" >> "$GITHUB_OUTPUT" + + test: + needs: [resolve] + permissions: + contents: read + uses: ./.github/workflows/test.yml + with: + ref: ${{ needs.resolve.outputs.sha }} + + build: + needs: [resolve] + permissions: + contents: read + uses: ./.github/workflows/build-app.yml + with: + ref: ${{ needs.resolve.outputs.sha }} + configuration: production + tag: ${{ needs.resolve.outputs.tag }} + secrets: inherit + + # Publish only after the tests pass + publish: + needs: [resolve, test, build] + runs-on: ubuntu-latest + timeout-minutes: 3 + env: + SHA: ${{ needs.resolve.outputs.sha }} + TAG: ${{ needs.resolve.outputs.tag }} + steps: + - uses: actions/checkout@v6 + with: + ref: ${{ needs.resolve.outputs.sha }} + + - name: Download build artifact + uses: actions/download-artifact@v4 + with: + name: build-output + path: dist/backoffice/browser + + # Vercel reads vercel.json from the pushed commit. Build branches + # hold only the built files, so add one that turns off deployments. + - name: Turn off Vercel deployments for the build branch + run: | + echo '{ "git": { "deploymentEnabled": false } }' > dist/backoffice/browser/vercel.json + + - name: Deploy the application + uses: MrYuion/git-publish-subdir-action@develop + env: + REPO: self + BRANCH: build/prod + FOLDER: dist/backoffice/browser + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + MESSAGE: 'build(backoffice): ${{ needs.resolve.outputs.tag }} from {sha}' + + # Pushes nothing when a retry already pushed the tag + - name: Push the release tag + run: git push origin "${SHA}:refs/tags/${TAG}" + + - name: Update Pipeline Chat Status + uses: fjogeleit/http-request-action@master + continue-on-error: true + with: + url: ${{ secrets.STATUS_URL }} + data: '{ "name": "${{ github.repository }}", "commit": "${{ needs.resolve.outputs.sha }}", "pipeline_name": "backoffice", "branch": "build/prod", "status": "${{ job.status }}", "url": "https://github.com/${{ github.repository }}/runs/${{ github.run_id }}" }' + if: ${{ always() }} + + # A separate job, so that a failed push to develop does not show as a failed + # deploy. Re-run this job alone to retry it. + changelog: + needs: [resolve, publish] + runs-on: ubuntu-latest + timeout-minutes: 2 + steps: + - uses: actions/checkout@v6 + with: + ref: develop + + - name: Download build artifact + uses: actions/download-artifact@v4 + with: + name: build-output + path: ${{ runner.temp }}/build + + - name: Commit the changelog to develop + env: + TAG: ${{ needs.resolve.outputs.tag }} + run: | + # A rollback has an older changelog. Keep the newer one. + newest="$(git ls-remote --tags origin | cut -f2 | sed 's|^refs/tags/||' \ + | grep -E '^v[0-9]+\.[0-9]{4}\.[0-9]+$' | sort -V | tail -1)" + if [[ "$newest" != "$TAG" ]]; then + echo "${newest} is newer than ${TAG}. CHANGELOG.md stays the same." + exit 0 + fi + + cp "${RUNNER_TEMP}/build/CHANGELOG.md" CHANGELOG.md + git add CHANGELOG.md + if git diff --cached --quiet; then + echo "CHANGELOG.md is already up to date." + exit 0 + fi + + git config user.name 'github-actions[bot]' + git config user.email 'github-actions[bot]@users.noreply.github.com' + git commit -m "docs(changelog): update for ${TAG}" + git push origin HEAD:develop diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 158961953..065dbe67c 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -6,20 +6,31 @@ on: paths-ignore: - 'docs/**' - '**/*.md' + # BUILD calls this workflow for develop, and RELEASE for a release commit workflow_call: - -# Cancel superseded runs of a pull request. BUILD calls this workflow for -# pushes; those runs get a unique group, so they never queue or cancel. + inputs: + ref: + description: 'Commit to test. Empty: the commit that started the run' + type: string + default: '' + +# Cancel superseded runs of a pull request. BUILD and RELEASE call this +# workflow; those runs get a unique group, so they never queue or cancel. concurrency: group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} cancel-in-progress: ${{ github.event_name == 'pull_request' }} +permissions: + contents: read + jobs: lint: runs-on: ubuntu-latest timeout-minutes: 3 steps: - uses: actions/checkout@v6 + with: + ref: ${{ inputs.ref }} - name: Setup Bun uses: oven-sh/setup-bun@v2 @@ -37,6 +48,8 @@ jobs: timeout-minutes: 5 steps: - uses: actions/checkout@v6 + with: + ref: ${{ inputs.ref }} - name: Setup Bun uses: oven-sh/setup-bun@v2 @@ -46,15 +59,6 @@ jobs: - name: Install dependencies run: bun install --frozen-lockfile - # Nx skips the tests when their inputs match a cached run. - - name: Cache nx build cache - uses: actions/cache@v5 - with: - path: .nx/cache - key: ${{ runner.os }}-nx-test-${{ github.sha }} - restore-keys: | - ${{ runner.os }}-nx-test- - - name: Setup version run: bun run postinstall @@ -65,13 +69,12 @@ jobs: # Playwright cannot install its browsers on ubuntu-latest (26.04) yet. # Move back to ubuntu-latest when Playwright supports it. runs-on: ubuntu-24.04 - timeout-minutes: 25 - env: - # Pull requests to develop and pushes to develop run Chromium only. - # Other branches run every browser. - CHROMIUM_ONLY: ${{ github.base_ref == 'develop' || github.ref == 'refs/heads/develop' }} + # A run takes about 5 minutes + timeout-minutes: 10 steps: - uses: actions/checkout@v6 + with: + ref: ${{ inputs.ref }} - name: Setup Bun uses: oven-sh/setup-bun@v2 @@ -87,10 +90,12 @@ jobs: # A browser cache saves no time here: a hit still installs the # system packages, and a restore takes about as long as a download. - name: Install Playwright browsers - run: bunx playwright install --with-deps ${{ env.CHROMIUM_ONLY == 'true' && 'chromium' || '' }} + run: bunx playwright install --with-deps chromium + # Chromium only. Firefox and WebKit took more than 25 minutes, and + # stopped releases. Run them locally with `bun run e2e`. - name: Run E2E tests - run: bunx nx e2e e2e ${{ env.CHROMIUM_ONLY == 'true' && '-- --project=chromium --project=mobile-chrome' || '' }} + run: bunx nx e2e e2e -- --project=chromium --project=mobile-chrome - name: Upload Playwright report uses: actions/upload-artifact@v4 diff --git a/.github/workflows/update-changelog.yml b/.github/workflows/update-changelog.yml deleted file mode 100644 index ea693b3bb..000000000 --- a/.github/workflows/update-changelog.yml +++ /dev/null @@ -1,53 +0,0 @@ -name: 'Update Changelog' - -on: - push: - tags: - - 'v[0-9]*' - -permissions: - contents: write - -concurrency: - group: update-changelog - cancel-in-progress: false - -jobs: - update_changelog: - runs-on: ubuntu-latest - steps: - - name: Checkout tag - uses: actions/checkout@v6 - with: - ref: ${{ github.ref }} - fetch-depth: 0 - - - name: Generate changelog - uses: orhun/git-cliff-action@v4 - with: - config: cliff.toml - args: --verbose - env: - OUTPUT: ${{ runner.temp }}/CHANGELOG.md - - - name: Checkout develop - uses: actions/checkout@v6 - with: - ref: develop - fetch-depth: 0 - - - name: Commit changelog - shell: bash - run: | - cp "${RUNNER_TEMP}/CHANGELOG.md" CHANGELOG.md - - if git diff --quiet -- CHANGELOG.md; then - echo "CHANGELOG.md is already up to date." - exit 0 - fi - - git config user.name 'github-actions[bot]' - git config user.email 'github-actions[bot]@users.noreply.github.com' - git add CHANGELOG.md - git commit -m "docs(changelog): update for ${{ github.ref_name }}" - git push origin HEAD:develop diff --git a/AGENTS.md b/AGENTS.md index fb5e60273..53dc7d2f6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -91,6 +91,7 @@ export class MyComponent extends AsyncHandler { - Dev proxy configured in `config/proxy.conf.js` (targets placeos-dev.aca.im) - Version info auto-generated to `src/env/version.ts` on postinstall - Production builds output to `dist/backoffice/browser` +- Releases follow PlaceOS/PlaceOS releases. Do not make `release/*` branches. See `docs/releases.md` ## Notes diff --git a/docs/releases.md b/docs/releases.md new file mode 100644 index 000000000..47fa93594 --- /dev/null +++ b/docs/releases.md @@ -0,0 +1,55 @@ +# Releases + +Backoffice releases follow the releases of +[PlaceOS/PlaceOS](https://github.com/PlaceOS/PlaceOS). Each PlaceOS release +ships the backoffice commit that its `interfaces/backoffice` submodule pins. +Thus the PlaceOS changelog agrees with the backoffice that installs get. + +## Branches + +| Branch | Contents | Updated by | +| ------------ | ------------------------------ | -------------------------------------------------- | +| `develop` | Source | Pull requests | +| `build/dev` | Development build of `develop` | `BUILD` (`.github/workflows/build.yml`), each push | +| `build/prod` | Production build of a release | `RELEASE` (`.github/workflows/release.yml`) | + +PlaceOS installs load backoffice from `build/prod`. `PlaceOS/init` sets this +branch when it creates the backoffice repository. + +Do not make `release/*` or `rc/*` branches. No workflow builds them. + +## How a release occurs + +1. Each night, PlaceOS/PlaceOS moves its `interfaces/backoffice` submodule to + the latest commit on `develop`. +2. The PlaceOS release team makes a release, for example `2.2611.6`. +3. The "Tag and release" job of the PlaceOS `build.yml` sends a + `placeos-release` event to this repository, with the version. +4. `RELEASE` finds the backoffice commit that `2.2611.6` pins. Then it: + 1. Tags the commit `v2.2611.6`. The version info in the build shows this tag. + 2. Runs lint, the unit tests and the Chromium e2e tests. + 3. Makes a production build and uploads the source maps to Sentry. + 4. Publishes the build to `build/prod` when the tests pass. + 5. Pushes the tag, and commits `CHANGELOG.md` to `develop`. + +## Get a change into a release + +Merge it to `develop`. The next PlaceOS release ships it. PlaceOS makes a +minor release approximately each week. For an urgent fix, ask the PlaceOS +release team to run "New Release" in PlaceOS/PlaceOS after the nightly +submodule update. + +## Retry or roll back a release + +Run `RELEASE` from the Actions tab, and enter a PlaceOS version. + +- To retry a failed release, enter the same version. A tag that a run pushed + before is used again. +- To roll back, enter an earlier version. `build/prod` gets the backoffice + of that version. `CHANGELOG.md` on `develop` does not change. + +`RELEASE` stops when: + +- The commit that PlaceOS pins is not on `develop`. Only reviewed code ships. +- The tag `v` is on a different commit than the commit that PlaceOS + pins. diff --git a/e2e/README.md b/e2e/README.md index 9f0638899..aadf25b66 100644 --- a/e2e/README.md +++ b/e2e/README.md @@ -37,8 +37,8 @@ The config starts the dev server, or uses the server that runs on port 4200. | `chromium`, `firefox`, `webkit` | `*.spec.ts` | | `mobile-chrome`, `mobile-safari` | `*.mobile.spec.ts` | -CI runs `chromium` and `mobile-chrome` for pull requests to `develop`, and -all projects on other branches. +CI runs `chromium` and `mobile-chrome` only. Run the other projects locally +before you change code that is specific to a browser. `USE_MOCK=false` stops the tests from switching on the mock backend. Most tests expect the mock data, so use this only to debug. To test against a real @@ -169,7 +169,7 @@ start needs access to GitHub. `.github/workflows/e2e-local.yml` runs this suite on a self-hosted runner with the label `placeos-e2e`. It runs: -- on a push to `develop`, `release/**`, `rc/**` and `e2e/**` +- on a push to `develop` and `e2e/**` - every day at 01:40 UTC - from **Run workflow**