@hominis/fireforge 0.54.0 → 0.60.0

package/docs/quality.md

@@ -0,0 +1,220 @@
+<!-- SPDX-License-Identifier: EUPL-1.2 -->
+
+# Quality: lint, policy, typecheck and check
+
+Every quality rule is defined over the **owned changes**: the paths the project adds, modifies or deletes relative to the pinned Firefox. Patch mode and source mode produce the same owned changes from different storage, so the rules mean the same in both. The owned changes come in **groups**: in patch mode a group is a patch; in source mode a group is a component of upstream changes, a group of created files, or the files one Furnace component deploys. Each has an ID, which `fireforge status --groups` lists ([source-workflow.md](source-workflow.md#groups)).
+
+## `lint`
+
+```sh
+npx fireforge lint
+npx fireforge lint browser/base/content/mybrowser
+npx fireforge lint --max-warnings 0
+npx fireforge lint --per-patch
+```
+
+`lint` runs every rule over the owned changes, applies the waivers, and prints one report. Findings have a severity: `error` fails the run, `warning` fails it only past `--max-warnings`, `notice` never fails it.
+
+- Paths limit which files' findings are reported. Findings about a whole group (size, policy) are always reported.
+- `--per-patch` (patch mode) judges the stored queue patch by patch instead of what `engine/` holds. CI should use it: it sees exactly what is committed.
+- `lint` takes no workspace. In source mode it reads `src/` and the pristine repository.
+
+### Rules
+
+`patchLint.rules` sets the severity of any rule (`off`, `notice`, `warning`, `error`), replacing its default. A rule whose default is `off` runs only when given a severity there.
+
+```json
+{ "patchLint": { "rules": { "jsdoc-class-method": "warning", "observer-topic-naming": "off" } } }
+```
+
+| Rule                           | Default | Meaning                                                                                                                |
+| ------------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `missing-license-header`       | error   | Files the project creates start with the project license header                                                        |
+| `modified-file-missing-header` | warning | Upstream files the project modifies still start with a recognised license header                                       |
+| `relative-import`              | error   | Owned JavaScript imports through `resource://` or `chrome://` URLs, not relative paths                                 |
+| `missing-modification-comment` | warning | An edit to upstream JavaScript carries the `// MARKER:` comment (`markerComment`, default the binary name in capitals) |
+| `jsdoc`                        | error   | Exports of created modules (`.sys.mjs`) carry JSDoc naming their parameters and return                                 |
+| `jsdoc-class-method`           | off     | Methods of exported classes of created modules carry JSDoc                                                             |
+| `chrome-script-jsdoc`          | off     | Top-level functions and classes of created chrome scripts carry JSDoc                                                  |
+| `test-needs-assertion`         | off     | Every owned or modified browser test makes at least one assertion                                                      |
+| `observer-topic-naming`        | warning | Observer topics carrying the binary name follow `<name>-<noun>-<verb>`                                                 |
+| `raw-color-value`              | error   | Owned stylesheet lines use custom properties instead of raw colours (`rawColorAllowlist` exempts files)                |
+| `token-prefix-violation`       | error   | Custom properties an owned stylesheet references are design tokens                                                     |
+| `token-scale`                  | error   | Properties a `tokenScales` entry governs, in created stylesheets, resolve to its scale tokens                          |
+| `token-scale-vacuous`          | error   | A scale with `minFiles` governs at least that many created stylesheets                                                 |
+| `stale-token-scale-exclude`    | warning | Every token-scale `exclude` names an owned path                                                                        |
+| `file-too-large`               | by band | Created JavaScript files stay under the size bands of their class (`fileSizeThresholds`)                               |
+| `large-patch-lines`            | by band | A patch's or component's own lines stay under the size bands of its tier (`patchSizeThresholds`)                       |
+| `large-patch-files`            | by band | A patch's or component's file count stays under the bands of its tier                                                  |
+| `mozbuild-unsorted-list`       | error   | Strict-ordered `moz.build` lists in owned files are sorted, as configure requires                                      |
+| `unregistered-system-module`   | error   | A created module that owned code imports by resource URL is installed by a `moz.build` list                            |
+| `dangling-registration`        | error   | Manifest entries the owned changes add name files that exist                                                           |
+| `forward-import`               | error   | Patch mode: no import names a module only a later patch creates                                                        |
+| `forward-registration`         | error   | Patch mode: no manifest entry names a file only a later patch creates                                                  |
+| `staged-dependency-unused`     | warning | Every declared staged dependency matches a forward reference                                                           |
+| `checkjs-type-error`           | error   | With `checkJs`, created modules (and with `checkJsTestFiles`, test scripts) type-check                                 |
+| `upstream-allowlist`           | error   | Upstream files change only where `patchPolicy` allows it                                                               |
+| `add-only`                     | error   | Add-only upstream files only gain lines carrying the marker                                                            |
+| `scope`                        | error   | Groups a scope rule selects touch only the files it names                                                              |
+| `policy-document-missing`      | error   | With `verifyDocumentPaths`, the decision records and documents of reviewed exceptions exist                            |
+| `lint-ignore-removable`        | notice  | A waiver ceiling is not needed: the rule reports nothing at warning or error on its group                              |
+
+The size rules report the band a measurement falls in: notice, warning or error. A severity in `patchLint.rules` replaces the band. The default bands:
+
+| Rule                | Class or tier | Notice | Warning | Error |
+| ------------------- | ------------- | -----: | ------: | ----: |
+| `file-too-large`    | general       |    500 |     750 |   900 |
+| `file-too-large`    | test          |   1200 |    1400 |  1600 |
+| `large-patch-lines` | general       |    800 |    1500 |  3000 |
+| `large-patch-lines` | test          |   1500 |    3000 |  6000 |
+| `large-patch-lines` | branding      |   8000 |   18000 | 30000 |
+| `large-patch-files` | general, test |        |       5 |       |
+| `large-patch-files` | branding      |        |      60 |       |
+
+The two patch-size rules judge patches in patch mode and components (upstream changes) in source mode. A source-mode group of created files, and the files of a Furnace component, are not sized as a group: each file answers to `file-too-large`.
+
+`fileSizeMetric` (`raw` or `code`) and `patchSizeMetric` (`diff` or `addedCode`) choose what is counted, and `patchSizeRegistrationFiles` lists registration files neither patch-size rule counts. A group is in the `test` tier when it changes only tests, and in `branding` when its `tier` says so.
+
+The `policy` rules take `error` from `patchPolicy`, or `warning` under `patchPolicy.mutationMode: "warn"`. [configuration.md](configuration.md) lists every `patchLint` key.
+
+### Waivers
+
+A waiver suppresses one rule's findings on one group. There are two forms:
+
+- A bare rule ID waives the rule at any size.
+- A ceiling `{ "rule", "max", "reason", "share"? }` waives a measured finding only while the measurement stays at or below `max`, so growth past the reviewed size surfaces again. A finding without a measurement is not waived. `share` (`product` or `test`) bounds that share of a `large-patch-lines` count. When a ceiling suppresses nothing at warning or error, `lint-ignore-removable` says so.
+
+Where they live:
+
+- **Patch mode**: in the patch's `lintIgnore` in `patches/patches.json`, edited with `patch set`:
+
+  ```sh
+  npx fireforge patch set ui-sidebar --lint-ignore file-too-large --reason "Generated table"
+  npx fireforge patch set ui-sidebar --lint-ignore large-patch-lines --max 1800 --reason "Reviewed: one feature"
+  npx fireforge patch set ui-sidebar --remove-lint-ignore file-too-large
+  ```
+
+- **Either mode**: in `patchLint.waivers` in `fireforge.json`:
+
+  ```json
+  {
+    "patchLint": {
+      "waivers": [
+        {
+          "group": "ui-sidebar",
+          "rule": "large-patch-lines",
+          "max": 1800,
+          "reason": "Reviewed: one feature"
+        }
+      ]
+    }
+  }
+  ```
+
+  `group` names the group. In patch mode that is the patch's name (`ui-sidebar`) or its file name (`012-ui-sidebar.patch`). In source mode it is the group's ID exactly as `fireforge status --groups` lists it: the component, the `exportQueue` group, `created-<directory>`, or the Furnace component. In source mode this is the only place for waivers; `migrate --to-source` moves each patch's `lintIgnore` here, and `export` writes them into the generated manifest.
+
+A finding is judged against the group it is attributed to and every group that changes its path.
+
+## Policy
+
+`patchPolicy` says which upstream files owned changes may touch and how. The `lint` rules `upstream-allowlist`, `add-only`, `scope` and `policy-document-missing` enforce it in both modes. The ordering half (`ranges`, `filenamePattern`, `requireDescription`, `allowGaps`) governs the patch queue and is described in [patch-workflow.md](patch-workflow.md#queue-operations-patch).
+
+```json
+{
+  "patchPolicy": {
+    "ranges": [
+      { "from": 1, "to": 99, "category": "branding" },
+      { "from": 100, "to": 499, "category": "ui" }
+    ],
+    "upstreamAllowlist": [
+      "browser/base/content/browser.js",
+      { "path": "browser/base/jar.mn", "addOnly": true },
+      "browser/themes/shared/**"
+    ],
+    "addOnlyMarker": "MYBROWSER",
+    "scopeRules": [{ "group": "-branding-", "files": ["browser/branding/**"] }]
+  }
+}
+```
+
+- A path is upstream when its first owned change is not a creation. Every group may change an upstream file only when an `upstreamAllowlist` glob matches it.
+- Under an `addOnly` entry a group may only add lines, each carrying the marker (`marker`, or `addOnlyMarker`), and remove lines that name one of the entry's `retiredPaths`.
+- A group named by a `reservedRanges[].allowed` entry is an exception: it may change the upstream files the entry's `files` lists (any, when it lists none) outside the allowlist, and its list must not name a file it does not change. With `verifyDocumentPaths`, its `adr` and `documentation` paths must exist.
+- `scopeRules[].group` is a regular expression over group IDs. Every file a selected group touches must match one of `files`. Patch-mode group IDs are patch file names (`012-ui-sidebar.patch`); source-mode group IDs are the names `fireforge status --groups` lists, used as they are (`ui-sidebar` for component `ui-sidebar`). A `reservedRanges[].allowed[].filename` names a group by the same ID.
+
+## `typecheck`
+
+```sh
+npx fireforge typecheck
+npx fireforge typecheck --project engine/browser/components/mybrowser/jsconfig.json
+npx fireforge typecheck --explain browser/base/content/mybrowser/panel.mjs
+```
+
+`typecheck` runs two passes as one result, green only when both are:
+
+1. Each `typecheck.projects` file (a `jsconfig.json` or `tsconfig.json`, project-relative) is checked whole, with its own compiler options plus the Firefox-globals shim: Firefox's privileged globals, Lit, and the test harness. A path under `engine/` names the file in the workspace's engine, so one configuration serves patch mode and source mode. `extraShim` adds a `.d.ts` to every project's shim, and `projectOverrides` gives one project another `.d.ts` or `null` for none.
+2. The owned files get lint's strict `checkJs` pass (when `patchLint.checkJs` is on).
+
+`--project <path>` checks other projects instead of `typecheck.projects`; repeat it for several. `--explain <file>` checks nothing and prints how both passes see the file: which programs include it, with which options and shim.
+
+The typing files Furnace generates must be current; `typecheck` refuses until `fireforge furnace types` has written them. Results are cached by the digest of every file a program read, so an unchanged program is not checked again.
+
+## `check`
+
+```sh
+npx fireforge check
+npx fireforge check --only lint --only typecheck
+npx fireforge check --skip furnace-validate
+```
+
+`check` runs the static checks as one judgement and ends with one verdict line ([machine-output.md](machine-output.md#check)):
+
+| Step               | Runs                                                     | Skipped when                        |
+| ------------------ | -------------------------------------------------------- | ----------------------------------- |
+| `status`           | `fireforge status`                                       |                                     |
+| `verify`           | `fireforge verify`                                       |                                     |
+| `lint`             | `fireforge lint`                                         |                                     |
+| `typecheck`        | `fireforge typecheck`, after `lint` (they share a cache) | `fireforge.json` has no `typecheck` |
+| `furnace-validate` | `fireforge furnace validate`                             | the project has no `furnace.json`   |
+| `token-coverage`   | `fireforge token coverage`                               | the project has no token file       |
+| `token-lint`       | `fireforge token lint`                                   | the project has no token file       |
+
+Steps run side by side unless one is ordered after another. The steps that need an engine (typecheck, component validation, extra steps declaring `engine`) share one workspace, leased when the first of them starts. A step with nothing to run is reported as skipped; `check.failOnSkipped` makes that a failure.
+
+`--only <step>` runs only the named steps and `--skip <step>` leaves steps out; both repeat. `check.skip` leaves built-in steps out for good.
+
+Per-step policy lives in the `check` section:
+
+- `status.failOn`: the status codes that fail the status step (every code when unset); `status.allow`: codes it accepts.
+- `maxWarnings.lint` and `maxWarnings.furnace`: the warning ceilings of those steps.
+- `minTokenCoverage`: the percentage below which `token-coverage` fails.
+- `lintReport`: a project-relative path the lint step writes its JSON report to.
+
+### Extra steps
+
+`check.extraSteps` adds your own commands:
+
+```json
+{
+  "check": {
+    "extraSteps": [
+      { "name": "eslint", "command": ["npx", "eslint", "src/"], "timeout": 300 },
+      {
+        "name": "policy-audit",
+        "command": ["node", "scripts/policy-audit.mjs"],
+        "after": ["lint"],
+        "engine": true
+      }
+    ]
+  }
+}
+```
+
+- `command` is an argument vector, run from the project root without a shell. The step passes on exit 0.
+- `timeout` (seconds, default 600) kills and fails a step that runs longer.
+- `after` names steps that must finish first, whatever their outcome.
+- `engine: true` runs the step holding the check's workspace.
+
+An extra step's environment carries `FIREFORGE_PROJECT_ROOT`, `FIREFORGE_OWNED_PATHS` (a file listing the owned engine paths, one per line), `FIREFORGE_CHECK_LINT_REPORT` when `check.lintReport` is set (order the step `after: ["lint"]` to read it), and `FIREFORGE_ENGINE`, the engine directory, for a step with `engine: true`.
+
+`check` exits 0 when every step that ran passed, 1 when a step failed, 8 for an unknown step name, and 15 when the workspace did not come free ([exit-codes.md](exit-codes.md#check)).

package/docs/source-workflow.md

@@ -0,0 +1,228 @@
+<!-- SPDX-License-Identifier: EUPL-1.2 -->
+
+# Source workflow
+
+In source mode (`"mode": "source"` in `fireforge.json`) the fork's changes are ordinary files tracked by git. This page covers how they map onto Firefox, how upstream files are declared, how FireForge brings them into a workspace, and how a patch queue is written from them. [getting-started.md](getting-started.md) shows the daily loop; [workspaces.md](workspaces.md) covers the workspaces builds run in.
+
+## The mapping
+
+```json
+{
+  "mode": "source",
+  "source": {
+    "root": "src",
+    "metadataRoot": ".fireforge-sources",
+    "pristineCommit": "3f1c...e9"
+  }
+}
+```
+
+- `source.root` (`src` by default): `src/<path>` supplies the Firefox file `<path>`. `src/browser/base/content/browser.js` is `browser/base/content/browser.js` in the engine.
+- `source.metadataRoot` (`.fireforge-sources` by default): holds one override record per upstream file the project touches.
+- `source.pristineCommit`: the commit the pinned Firefox archive imports as. Every host derives the same commit from the same archive, so the pin is exact.
+
+A file under `src/` whose path Firefox does not have is a created file. It needs nothing else. A file whose path Firefox has needs an override record, which says which upstream version the edit started from.
+
+The owned files are what git sees in the working tree: tracked files and untracked files git does not ignore. FireForge never captures or retains a copy, so two clean checkouts of one commit read the same. `src/.gitattributes` and `src/.gitignore` configure git and are not engine files.
+
+## Declaring an upstream file: `override`
+
+```sh
+npx fireforge override browser/base/content/browser.js
+$EDITOR src/browser/base/content/browser.js
+```
+
+`override` writes the record and copies the pristine bytes to `src/<path>` for you to edit. An edit made before the override is refused: move it aside, run `override`, and put it back.
+
+- `--delete` declares that the project deletes the upstream file. The record is a tombstone and there is no owned file.
+- `--component <name>`: the component the change belongs to: a group of upstream changes that lint, policy and waivers name by this name, and one patch of an export ([Groups](#groups)). The default is the path's top directory.
+- `--classification registration|exception`: `registration` (the default) wires an addition into Firefox, such as a `jar.mn` line; `exception` is a reviewed change to upstream behaviour and needs `--adr <path>`, a decision record in the project.
+
+The record lives at `<metadataRoot>/overrides/<path>.json`:
+
+```json
+{
+  "base": {
+    "blob": "8c3f0d2a5e1b4c7d9f6a2b0e3d5c7a9b1e4f6d8c",
+    "commit": "3f1c7b2d9e0a4c6f8b1d3e5a7c9f0b2d4e6a8c1f",
+    "mode": "100644"
+  },
+  "classification": "registration",
+  "component": "browser",
+  "kind": "override"
+}
+```
+
+`base` is the upstream identity: the pristine commit, the file's blob and mode at that commit. `kind` is `override` or `delete`.
+
+The first override in a repository also configures the merge driver (see below).
+
+The commands that edit tracked files for you (`register`, `wire`, `token add`, `furnace`) write the owned copy under `src/`. Their first edit of an upstream build manifest declares its override as a `registration` on the way.
+
+## Giving a file back: `restore`
+
+```sh
+npx fireforge restore browser/base/content/browser.js
+```
+
+`restore` removes the record and the owned file; the next build brings the upstream bytes back into the workspace. It refuses while the owned file has uncommitted edits; `--discard` drops them.
+
+## `status` and `verify`
+
+```sh
+npx fireforge status
+npx fireforge verify
+```
+
+Both read `src/` and the pristine repository directly; neither needs a workspace or a build.
+
+`status` lists every owned path with its group, and these problems:
+
+| Code                 | Meaning                                                                                   |
+| -------------------- | ----------------------------------------------------------------------------------------- |
+| `undeclared`         | The file exists upstream but has no override record                                       |
+| `stale`              | The record's base is not the pinned upstream file, or the path is not upstream at the pin |
+| `orphaned`           | A record without its owned file                                                           |
+| `adr-missing`        | An exception whose decision record does not exist                                         |
+| `ignored`            | A file under `src/` that git ignores, so a commit would not hold it                       |
+| `filtered`           | Git attributes (`text`, `eol`, `filter`, ...) could change the file's bytes on commit     |
+| `unmerged`           | An unresolved merge conflict                                                              |
+| `tombstone-has-file` | A `delete` record with an owned file beside it                                            |
+| `case-collision`     | Two paths that differ only in case                                                        |
+| `unsupported-kind`   | A link, submodule or directory where a regular file belongs                               |
+| `path-conflict`      | A file where upstream has a directory, or the reverse                                     |
+| `invalid-path`       | A path Firefox cannot hold                                                                |
+| `invalid-record`     | A record that does not parse or does not match its schema                                 |
+
+Each problem carries the command that fixes it. The last seven make a path's content undefined: builds, tests and `export` refuse until they are fixed. `status --check` exits 1 while anything is listed.
+
+`verify` checks every override record and owned file against the pristine repository and reports the same kinds of problem.
+
+## Groups
+
+Every owned path is in exactly one group. A group is what `patchLint.waivers`, `patchPolicy.scopeRules`, `patchPolicy.reservedRanges` and lint findings name, and one patch of an export. Its ID is a name the project wrote, used as it is:
+
+| Group                                               | ID                                                       |
+| --------------------------------------------------- | -------------------------------------------------------- |
+| The upstream changes of a component                 | The component, as the override records spell it          |
+| Created files an `exportQueue.groups` entry matches | The entry's `name`                                       |
+| The remaining created files, by directory           | `created-<directory>`, such as `created-browser-modules` |
+| The files a Furnace component deploys               | The component's tag, such as `moz-my-widget`             |
+
+```sh
+npx fireforge status --groups
+```
+
+```
+214 owned path(s) in 4 group(s), and 1 Furnace component(s)
+  ui-sidebar  component  3 path(s)
+  created-browser-modules  created  180 path(s)
+  ui-tiles  created  31 path(s)
+  moz-my-widget  furnace  2 path(s)
+```
+
+An ID depends only on the group's own names and paths: adding a group renames nothing, and an export's numbering is no part of it. Two groups may not share an ID (`source-group-name-collision`): give the `exportQueue` group another name than the component.
+
+The size rules (`large-patch-lines`, `large-patch-files`) judge components, whose extent is the fork's reach into upstream. Created files and Furnace components are judged file by file (`file-too-large`), whatever group they are in.
+
+## Materialization
+
+A workspace is an engine checkout with its build, kept under `~/.fireforge/workspaces/`. Every command that works in a workspace (the ones with a `--workspace` option, and `gate`) leases one and first materializes the checkout into it: the engine becomes exactly the pristine commit plus your owned files. It then deploys the Furnace components, so the engine holds what this checkout builds whichever checkout leased it before.
+
+- Only paths that differ are written. A ledger in the workspace remembers what was written for each owned file and the file's size, modification time, change time and inode, so an unchanged run reads no file content.
+- A path the ledger records and the checkout does not own gets its upstream bytes back, or is removed when upstream has none.
+- Two checkouts can lease the same workspace one after the other; each lease writes only the difference.
+- The writes and the ledger update are one transaction. An interrupted materialization is undone before the next one looks at the engine.
+
+**The drift rule.** Materialization changes an engine file only when the file holds bytes it can account for: what it wrote last time, what Furnace deployed on top of that, or the pristine bytes for a path it never wrote. Anything else was changed by someone else (an editor pointed into the workspace, a script), and the command stops with `materialize-drift`, listing the files:
+
+```
+Engine files changed outside FireForge; materialization would overwrite them:
+  browser/base/content/browser.js
+```
+
+Save what you need from those files, then reset the workspace and run the command again:
+
+```sh
+npx fireforge workspace repair w1
+```
+
+Edit the files under `src/`, never the files inside a workspace.
+
+## Writing a patch queue: `export`
+
+```sh
+npx fireforge export
+npx fireforge export --out ../mybrowser-patches
+```
+
+`export` writes the owned changes as a patch queue that `fireforge import` in a patch-mode project replays byte for byte, for a public mirror, for CI that consumes patches, or to go back to patch mode. It writes into `patches/` by default or into `--out`, which must be empty or hold a queue FireForge generated. Before anything is written, the queue is replayed onto the pristine commit and must produce exactly the tree this checkout builds.
+
+The patches are the [groups](#groups) of the owned paths under `src/`, one patch each:
+
+1. Every component is one patch: all modified and deleted upstream files with that component.
+2. Created files follow, because a created file can take the place of an upstream file a component deletes. A created file joins the first `exportQueue.groups` entry one of whose globs matches it.
+3. The remaining created files group by directory: the deepest directory whose files together fit `exportQueue.maxGroupBytes` (1 MiB by default) is one patch.
+
+Within each of the two, patches apply in ID order, and are numbered from 1. A patch is named after its group's ID in lowercase with other characters as hyphens; an ID spelled like a patch file (`012-ui-sidebar.patch`) gives that name (`ui-sidebar`). Nothing is put in front of a name: its first word is the patch's category. An ID that leaves no name starting with a letter cannot be exported (`source-group-unexportable`), and two IDs that give one name collide. Each path is in exactly one patch, so no patch depends on another's context, and an edit to one file changes only that file's patch.
+
+The files Furnace deploys are not in the queue: a consumer gets them from `components/` and `furnace.json`, which deploy at its build.
+
+The manifest carries each patch's tier (from `exportQueue.componentTiers` or the group's `tier`) and the lint waivers `patchLint.waivers` declares for its group.
+
+## The merge driver
+
+Two branches that each first-touch one upstream file both add `src/<path>` with no common ancestor in the project's history, so plain git sees an add/add conflict over the whole file. FireForge's merge driver merges them against the pristine blob the override record names instead.
+
+`src/.gitattributes` routes owned files through it:
+
+```
+* -text
+* merge=fireforge
+```
+
+The driver itself is configured in the repository's git config, shared by all its worktrees. The first `override` installs it; to install it in a fresh clone:
+
+```sh
+npx fireforge merge-driver install
+```
+
+The driver needs Git 2.44 or later, which tells it which commit the ancestor came from. It uses the pristine blob only when that commit lacks the path. With an older Git, or when no single merge base exists (several merge bases, `git am -3`, a stash), it merges the empty ancestor as given, which is git's own add/add conflict.
+
+## Moving to another Firefox version: `rebase`
+
+```sh
+git status   # must be clean
+npx fireforge rebase --to 140.10.0esr
+```
+
+`rebase` needs a committed tree. It downloads the version (`--product`, `--sha256`, `--candidate`), then merges every owned file three ways: the old pristine file is the base, your file is ours, the new pristine file is theirs. The result is written to `src/`, the override records and the pin in `fireforge.json` in one transaction. Review it with `git diff`; undo it with git.
+
+A conflict is left the way git leaves one: conflict markers in the owned file, and the three versions as unmerged entries in the index, so `git status` lists it, `git checkout --ours` or `--theirs` picks a side, and a commit is refused until it is resolved. The records of conflicted paths already name the new upstream file, so resolving is only a matter of the file's content. `rebase` exits 10 when conflicts remain.
+
+```sh
+$EDITOR src/browser/base/content/browser.js
+git add src/browser/base/content/browser.js
+npx fireforge status
+git commit -am "Rebase onto 140.10.0esr"
+```
+
+`--continue`, `--abort` and `--dry-run` belong to patch mode; in source mode git is the undo.
+
+## Coming from patch mode, going back
+
+`fireforge migrate --to-source` converts a committed patch-mode project in place ([patch-workflow.md](patch-workflow.md#moving-to-source-mode)). Each patch becomes a component, and `exportQueue.groups` keeps each patch's created files together (as `<patch>-created` when the patch also changed upstream files), so a later `export` writes a queue shaped like the one you had.
+
+To go back to patch mode:
+
+```sh
+npx fireforge export
+```
+
+Then edit `fireforge.json` by hand: set `"mode": "patches"` and remove the `source` block (`config set` refuses to change `mode`, because the two keys change together). Remove `src/` and the metadata root, and apply the queue to a fresh engine:
+
+```sh
+git rm -r src .fireforge-sources
+npx fireforge download
+npx fireforge import
+```