From 35455c2ef6e33ce94d59051aa06ff3de91946030 Mon Sep 17 00:00:00 2001 From: PointStar Date: Sun, 24 May 2026 19:35:51 +0300 Subject: [PATCH] docs(briefing): document the live release pipeline + Klear rebrand boundary Replaces the stale "Things deliberately deferred" entries (CI runner, codesign cert, platform.dev hosting, Mattermost webhook) with a new "How releases work (current)" section that captures what's actually running today: - Production install URL = platform.dev.marcus-law.co.il/outlook-addin/ - Tag-driven Gitea Actions pipeline in .gitea/workflows/build.yml - Real codesign cert lives in Gitea secrets, dev cert in repo - Klear visible rebrand boundary: what shipped in v1.2.0 vs what stays MarcusLaw to preserve auto-update across the 10 installed lawyer PCs - The dropped Publish/ folder was never the production channel The "deferred" table now only mentions the identity-level Layer-2 rebrand, which is the only thing actually still open. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/PROJECT-BRIEFING.md | 41 ++++++++++++++++++++++++++++++++++++---- 1 file changed, 37 insertions(+), 4 deletions(-) diff --git a/docs/PROJECT-BRIEFING.md b/docs/PROJECT-BRIEFING.md index 567660c..6989f40 100644 --- a/docs/PROJECT-BRIEFING.md +++ b/docs/PROJECT-BRIEFING.md @@ -268,14 +268,47 @@ If the session is on the Linux dev server (`/home/chaim/espocrm-extensions/Outlo --- +## How releases work (current, 2026-05-24) + +**Production install URL:** `https://platform.dev.marcus-law.co.il/outlook-addin/OutlookAddin.vsto` + +**Release flow:** + +1. Code change merged to `main` (push or PR-merge — no CI fires yet) +2. Bump `` in `src/OutlookAddin/OutlookAddin.csproj` and `AssemblyVersion` + `AssemblyFileVersion` in `src/OutlookAddin/Properties/AssemblyInfo.cs` to the next 4-part version (e.g. `1.2.1.0`). CI overrides `ApplicationVersion` from the tag at build time, but leaves AssemblyInfo alone — keep them in sync manually so the bundled DLL's FileVersion matches the manifest. +3. `git tag -a v1.2.1 -m "..." && git push --tags` +4. Gitea Actions workflow (`.gitea/workflows/build.yml`) fires: + - Imports the **real** codesign cert from secrets `CODESIGN_CERT_PFX_BASE64` + `CODESIGN_THUMBPRINT` (publicKeyToken `c68d2b4c25051c5b`, `CN=Marcus-Law OutlookAddin`) + - Patches csproj to swap the dev self-signed thumbprint (`2399E9BF…`) for the real one + - `msbuild /t:Publish` with `/p:InstallUrl=https://platform.dev.marcus-law.co.il/outlook-addin/` and `/p:ApplicationVersion=.0` + - Uploads `publish.tar.gz` to Gitea generic registry (`outlook-addin-publish//publish.tar.gz`) + - Linux job downloads the tar.gz, builds a Docker image `outlook-addin-cdn:latest`, pushes to Gitea registry, calls Coolify to redeploy the CDN container + - Posts to Mattermost channel `git-verelasim` with the install URL on success / a failure link on failure +5. Lawyers' installed Add-in checks the deployment manifest at the install URL every 7 days (configured in csproj `7`) or whenever they click "בדוק עדכונים" in Settings → אודות. + +**Semver policy:** PATCH for bug fixes (unilateral), MINOR for visible features (unilateral when warranted), MAJOR only with Chaim's explicit approval. + +**Branding (`KlearBranding` repo):** the product is presented to lawyers as **Klear** — title bars, MessageBox titles, ribbon group label, About header all say "Klear". The logo is mirrored from `espocrm-extensions/KlearBranding/files/client/custom/img/logo-klear.png` into `src/OutlookAddin.UI/Resources/logo-klear.png` and embedded as a WPF Resource. Brand accent color: `#121d2e` (dark navy). + +**What stays MarcusLaw under the hood (deliberate — preserves auto-update across the rebrand):** +- ClickOnce app identity (`AssemblyName=MarcusLaw.OutlookAddin`) +- `%APPDATA%\MarcusLaw\OutlookAddin\settings.json` and `creds.dat` +- `%LOCALAPPDATA%\MarcusLaw\OutlookAddin\logs\` +- `DpapiCredentialStore.EntropySeed = "MarcusLaw.OutlookAddin.v1"` +- Code namespaces `MarcusLaw.OutlookAddin.*` +- Named pipe `MarcusLaw.OutlookAddin` + +Changing any of these would orphan all existing installs and require a coordinated uninstall+reinstall on every lawyer's PC plus an entropy migration for DPAPI-encrypted credentials. See the LegalCRM rebrand misadventure in git history for what *not* to do. + +**Known traps when releasing:** +- VS Publish wizard (Project Properties → Publish) **rewrites** csproj at every click — flips `` back to `true`, resets `` to whatever's in the UI, sometimes deletes prior `Application Files/<...>/` bundles. **Don't use it.** Tag and let CI do it. +- There's an old `Publish/` directory in git history that was a parallel manual-release channel via `gitea.../raw/branch/main/Publish/`. It's **not the production install URL** — that's platform.dev. The folder was dropped in v1.2.0. + ## Things deliberately deferred | What | When | Why deferred | |---|---|---| -| Windows CI runner on Coolify | Until ClickOnce publish becomes useful | Local builds on dev's VS 2022 suffice through week 5 | -| Code signing cert (self-signed) + GPO push to 10 PCs | Week 6 (before release) | IT task; cert isn't useful until we have something to sign | -| ClickOnce hosting setup at `platform.dev.marcus-law.co.il/outlook-addin/` | Week 6 | No build artifacts yet | -| Mattermost release notification webhook in CI | Week 6 | Coupled to CI runner | +| Identity-level rebrand to a pure Klear product (AssemblyName, namespaces, DPAPI entropy, AppData paths) | Until there's another reason to force-reinstall on all 10 PCs | Visible rebrand already done in v1.2.0 without disrupting users; full rename trades aesthetic cleanliness for a day of IT coordination + lost credentials | ---