mirror of
https://github.com/LGUG2Z/komorebi.git
synced 2026-11-22 08:31:50 +01:00
docs(dev): the cutover account in the map, the summary and the unified-binaries note
ARCHITECTURE-UNIFIED.md: the status line, section 1 (a table of where each platform is now), the package paragraph (shims gone, version crate), the oracle paths (schemas/*, docs/*/cli), section 6 (now "done / still open" instead of "what is still the old layout"), the tier-0 row, and the helper tools paragraph (tools/ is committed now). MIGRATION-SUMMARY.md: status line, the three-trees paragraph, the oracle paths, the known issues paragraph, and section 7, which was "Cutover list (not done)" and is now a table of what the cutover stack did and what is open; item 7 of "How to continue". unified-binaries.md: the status banner (with a map from the old directory names to the new ones), the Mac Mini commands (the shim line removed, schema.bar.json under schemas/macos, `komorebi 0.2.0`), and "What is left for the cutover" is now a done / still open list. Still open, as stated in the three: the one flake (flake-one is writing it), CI and release workflows (the old ones are archived in docs/dev/old-ci), the site and repository URLs, COMPARE.md. The 0.1.42 / 0.1.0 / 0.1.1 numbers and the old directory names that stay in narrative sections are history and are marked as such. Not touched: build-and-test.md and flake.md (owned by flake-one). Verified: the relative links of the three files resolve. The statements about what the stack did are taken from the revision descriptions of wip-cutover, not re-measured.
This commit is contained in:
1 parent
f82fe692fc
commit
1b3178cede
3 files changed
+121
-76
No files matched your search
@@ -1,29 +1,36 @@
|
||||
# komorebi after the consolidation: a map of the repository
|
||||
|
||||
Status (wip-cand4): current map. Windows, KDE Plasma and macOS build from one workspace and one
|
||||
`komorebi`, one `komorebic`, one `komorebi-client` and one `komorebi-bar` package, the platform chosen by
|
||||
`cfg(target_os)`. The cutover (shim packages, one flake, final directories, one version number) is not done;
|
||||
section 6 lists what is still old. macOS has only been type-checked on Linux and compiled/unit-tested on a
|
||||
Mac Mini; no macOS daemon behaviour has been observed.
|
||||
Status (the cutover stack, `wip-cutover`): current map. Windows, KDE Plasma and macOS build from one
|
||||
workspace (version 0.2.0) and one `komorebi`, one `komorebic`, one `komorebi-client` and one `komorebi-bar`
|
||||
package, the platform chosen by `cfg(target_os)`. The shim packages are gone, the directories are the final
|
||||
ones and there is one `komorebi-version` crate; the one flake is being written by another agent
|
||||
(`flake-one`) and CI and releases are not done: section 6 says what is done and what is open. macOS has
|
||||
only been type-checked on Linux and compiled/unit-tested on a Mac Mini; no macOS daemon behaviour has been
|
||||
observed. Documents below that give a measurement or a decision keep the paths and numbers of their time
|
||||
(`komorebi-for-kde/`, `komorebi-for-mac/`, 0.1.42, `kfde-*`); the table in section 1 says where things are now.
|
||||
|
||||
How to build and test: [build-and-test.md](build-and-test.md). Why things are shaped as they are:
|
||||
[seam.md](seam.md) (the `Backend` trait), [core-model.md](core-model.md) (the shared model),
|
||||
[settings.md](settings.md), [unified-binaries.md](unified-binaries.md), [bar-unification.md](bar-unification.md),
|
||||
[backend-switch.md](backend-switch.md). What a person with a Mac has to check: [macos-handcheck.md](macos-handcheck.md).
|
||||
|
||||
## 1. Three platform trees, one workspace
|
||||
## 1. Three platforms, one workspace, one directory level
|
||||
|
||||
The root `Cargo.toml` is the only workspace. It has members in three places:
|
||||
The root `Cargo.toml` is the only workspace. Its members are all at the top level or under `crates/`;
|
||||
the platform-specific parts are:
|
||||
|
||||
| Tree | What is in it | Platform |
|
||||
| Platform | Where it is | What is in it |
|
||||
|---|---|---|
|
||||
| the repository root (`komorebi/`, `komorebi-bar/`, `komorebic/`, ...) | the Windows daemon library, the unified packages, the Windows-only tools (`komorebi-gui`, `komorebi-shortcuts`, `komorebic-no-console`), `komorebi-layouts`, `komorebi-scrolling`, `komorebi-themes`, `e2e/`, `wix/` | Windows (the original) |
|
||||
| `komorebi-for-kde/` | the KDE daemon library `komorebi-linux` (`komorebi/`), `komorebi-hotkeys/`, the `version-linux` crate, the NixOS module, the VM test suites (`nix/tests/vm`), KDE docs (`docs/dev`) | Linux, KDE Plasma on KWin (Wayland) |
|
||||
| `komorebi-for-mac/` | the macOS daemon library `komorebi-macos` (`komorebi/`), the `version-macos` crate, the nix darwin module, macOS docs | macOS |
|
||||
| Windows (the original) | `komorebi-windows/` (the daemon library), `komorebi-bar/`, `komorebic/`, `komorebi-gui/`, `komorebi-shortcuts/`, `komorebic-no-console/`, `komorebi-layouts/`, `komorebi-scrolling/`, `komorebi-themes/`, `e2e/`, `wix/`; docs in `docs/` | the Windows daemon library, the unified packages, the Windows-only tools |
|
||||
| Linux, KDE Plasma on KWin (Wayland) | `komorebi-linux/` (the daemon library), `komorebi-hotkeys/`, `nix/linux/` (NixOS module, VM test suites in `nix/linux/tests/vm`, KWin effects), `scripts/linux/`, `spikes/`; docs in `docs/linux/` | the KDE daemon library, the key binding crate, the NixOS module and the VM tests |
|
||||
| macOS | `komorebi-macos/` (the daemon library), `nix/macos/`; docs in `docs/macos/` | the macOS daemon library and the nix-darwin module |
|
||||
|
||||
`komorebi-for-kde/` and `komorebi-for-mac/` still have their own flakes, `justfile`s and docs; the root flake
|
||||
imports them as `kfde-*` and `kfm-*` (section 5). They have no `Cargo.toml` workspace of their own any more:
|
||||
`cargo` run inside them uses the root one.
|
||||
Shared: `crates/` (including `crates/komorebi-version`, the version string of the Linux and macOS
|
||||
binaries), `schemas/{windows,linux,macos}/` (the generated JSON schemas), one `deny.toml`, `rustfmt.toml`,
|
||||
`rust-toolchain.toml`, `.gitignore`, `LICENSE.md` and `justfile` at the root. The old repositories'
|
||||
workflows, dependabot files, the Homebrew formula template and the macOS docs-site files are kept, inert, in
|
||||
`docs/dev/old-ci/{linux,macos}/` for the CI and release plan. There is no `komorebi-for-kde/` or
|
||||
`komorebi-for-mac/` any more except the two flakes that `flake-one` is replacing.
|
||||
|
||||
## 2. The packages (what a user runs)
|
||||
|
||||
@@ -34,14 +41,14 @@ imports them as `kfde-*` and `kfm-*` (section 5). They have no `Cargo.toml` work
|
||||
| `komorebi-client` (library) | `komorebi-client/` | `src/windows.rs`, `src/linux.rs`, `src/macos.rs` re-export the daemon library of the target OS behind one `Connection` |
|
||||
| `komorebi-bar` (`komorebi-bar`) | `komorebi-bar/` | `src/windows/` and `src/macos/` modules; shared code in `crates/komorebi-bar-core`. **KDE has no bar** |
|
||||
|
||||
The daemon libraries are `komorebi-windows` (`komorebi/`), `komorebi-linux` (`komorebi-for-kde/komorebi/`) and
|
||||
`komorebi-macos` (`komorebi-for-mac/komorebi/`). They have no binary: each has a `daemon.rs` with
|
||||
`run()`, the old `main`. `-p komorebi-windows` etc. still build, as libraries.
|
||||
The daemon libraries are `komorebi-windows` (`komorebi-windows/`), `komorebi-linux` (`komorebi-linux/`) and
|
||||
`komorebi-macos` (`komorebi-macos/`). They have no binary: each has a `daemon.rs` with
|
||||
`run()`, the old `main`. `-p komorebi-windows` etc. build them, as libraries.
|
||||
|
||||
Shim packages exist until the cutover (each is a `#[path]` include of the unified module, same binary
|
||||
name): `komorebic-linux`, `komorebic-macos`, `komorebi-client-linux`, `komorebi-client-macos`,
|
||||
`komorebi-bar-macos`. Never build `komorebic` together with `komorebic-linux` or `komorebic-macos`: the
|
||||
binary name is the same.
|
||||
The shim packages (`komorebic-linux`, `komorebic-macos`, `komorebi-client-linux`, `komorebi-client-macos`,
|
||||
`komorebi-bar-macos`, each a `#[path]` include of the unified module) were deleted in the cutover stack, and
|
||||
so were `version-linux` and `version-macos` (now `crates/komorebi-version`). To build a platform use the
|
||||
one package name, for example `-p komorebic -p komorebi-client -p komorebi-bar -p komorebi-macos` on macOS.
|
||||
|
||||
## 3. The shared crates (`crates/`)
|
||||
|
||||
@@ -76,7 +83,7 @@ These are intentional, not leftovers; before "unifying" one, read the document n
|
||||
- The bar: [bar-unification.md](bar-unification.md): one package, one module per OS; rendering code differs
|
||||
(frame margins, `network.rs`, window seams) and B4 (merging it) was not done.
|
||||
- Command line: each platform keeps its help text and its own commands (Windows 34, KDE 2, macOS 1 are
|
||||
platform-only; most are common). `komorebic` pages in `docs/cli` of each tree are the oracle.
|
||||
platform-only; most are common). `komorebic` pages in `docs/cli`, `docs/linux/cli` and `docs/macos/cli` are the oracle.
|
||||
- macOS: everything except compile and unit tests is unverified; [macos-handcheck.md](macos-handcheck.md).
|
||||
- KDE: no bar; hotkeys through `komorebi-hotkeys` and exported KDE shortcuts; the module is NixOS.
|
||||
- Windows: the e2e under QEMU (`e2e/`), `komorebi-gui`, `komorebi-shortcuts`, `komorebic-no-console`, wix.
|
||||
@@ -86,10 +93,10 @@ These are intentional, not leftovers; before "unifying" one, read the document n
|
||||
| Oracle | Where | Detects | Run by |
|
||||
|---|---|---|---|
|
||||
| Wire goldens | `crates/komorebi-protocol/tests/golden*` | a change of what each daemon sends or accepts on the socket | `cargo test -p komorebi-protocol` |
|
||||
| Config schemas | `schema.json`, `schema.asc.json` of the three trees; `crates/komorebi-config/tests/schemas.rs`; KDE `komorebi/tests/schemas.rs` | a changed key of `komorebi.json` | `cargo test -p komorebi-config` (KDE: `-p komorebi-linux --test schemas -- --test-threads=1`) |
|
||||
| Bar schema views | `schema.bar.json` (Windows), `komorebi-for-mac/schema.bar.json`; `crates/komorebi-bar-core/tests/schema_oracle.rs` pins size and hash; `komorebi-bar --schema` prints the view of the target OS | a changed bar configuration | `cargo test -p komorebi-bar-core`; Windows e2e scenario `bar` compares `--schema` byte for byte |
|
||||
| CLI docs | `docs/cli` of each tree; `crates/komorebic-core/tests/docs_cli.rs` and `platforms.rs` | a changed subcommand or help text | `cargo test -p komorebic-core`; `komorebic docgen --output DIR` regenerates |
|
||||
| Schema docs completeness | `check_schema_docs.py` (root) | schema entries with no description | by hand |
|
||||
| Config schemas | `schemas/{windows,linux,macos}/schema.json` and `schema.asc.json`; `crates/komorebi-config/tests/schemas.rs`; KDE `komorebi-linux/tests/schemas.rs` | a changed key of `komorebi.json` | `cargo test -p komorebi-config` (KDE: `-p komorebi-linux --test schemas -- --test-threads=1`) |
|
||||
| Bar schema views | `schemas/windows/schema.bar.json`, `schemas/macos/schema.bar.json`; `crates/komorebi-bar-core/tests/schema_oracle.rs` pins size and hash; `komorebi-bar --schema` prints the view of the target OS | a changed bar configuration | `cargo test -p komorebi-bar-core`; Windows e2e scenario `bar` compares `--schema` byte for byte |
|
||||
| CLI docs | `docs/cli`, `docs/linux/cli`, `docs/macos/cli`; `crates/komorebic-core/tests/docs_cli.rs` and `platforms.rs` | a changed subcommand or help text | `cargo test -p komorebic-core`; `komorebic docgen --output DIR` regenerates |
|
||||
| Schema docs completeness | `check_schema_docs.py` (root; the macOS copy is archived in `docs/dev/old-ci/macos/`) | schema entries with no description | by hand |
|
||||
| Drift of derivations | `nix eval .#packages.x86_64-linux.default.drvPath` and the check derivations | an unintended change of what nix builds | by hand (see build-and-test.md) |
|
||||
| Backend contract | `komorebi-backend/src/contract.rs` | a backend that breaks a rule of the trait | `cargo test -p komorebi-backend` and each daemon's tests |
|
||||
| Runtime | Windows e2e (QEMU), KDE VM suites | real behaviour | tier 3 below |
|
||||
@@ -97,37 +104,58 @@ These are intentional, not leftovers; before "unifying" one, read the document n
|
||||
Windows `docs/cli` was found stale against the binary in the step-4 measurement (see the progress notes,
|
||||
decision D20); regenerate before treating it as an oracle.
|
||||
|
||||
## 6. What is still the old layout (cutover list)
|
||||
## 6. The cutover: done, and still open
|
||||
|
||||
Shim packages and their directories under `komorebi-for-kde/` and `komorebi-for-mac/`; `version-linux` and
|
||||
`version-macos`; three flakes (the root one imports the other two as `kfde-*` and `kfm-*`); three `deny.toml`;
|
||||
three version numbers (Windows libraries and packages 0.1.42, KDE 0.1.0, macOS library 0.1.1 and its `version` crate 0.1.0). Some docs still describe the old layout; those that were
|
||||
found wrong have been corrected, [COMPARE.md](../../komorebi-for-kde/docs/dev/COMPARE.md) is marked stale.
|
||||
`komorebi-for-kde/justfile` still has recipes written for a KDE-only workspace (`just check` runs
|
||||
`cargo test --workspace`, which on Linux would build the Windows crates): use the commands in
|
||||
build-and-test.md.
|
||||
Done in the cutover stack (`jj log -r 'wip-main..wip-cutover'`, one revision per concern):
|
||||
|
||||
- one workspace version, 0.2.0, for every package (the tables of older documents that say 0.1.42, 0.1.0
|
||||
and 0.1.1 are history); one `komorebi-version` crate instead of `version-linux` and `version-macos`;
|
||||
- the shim packages `komorebic-linux`, `komorebic-macos`, `komorebi-client-linux`, `komorebi-client-macos`
|
||||
and `komorebi-bar-macos` deleted;
|
||||
- the directories renamed: `komorebi/` to `komorebi-windows/`, the KDE and macOS libraries to
|
||||
`komorebi-linux/` and `komorebi-macos/`, `komorebi-hotkeys/` to the top level; `docs/{linux,macos}`,
|
||||
`nix/{linux,macos}`, `scripts/linux`, `spikes/`, `schemas/{windows,linux,macos}`;
|
||||
- one `deny.toml`, `rustfmt.toml`, `rust-toolchain.toml`, `.gitignore`, `LICENSE.md` and `justfile`;
|
||||
`tools/format-all` checks one group;
|
||||
- the documents, scripts and comments that named the old paths name the new ones (the Windows docs site
|
||||
excludes `docs/linux`, `docs/macos` and `docs/dev`).
|
||||
|
||||
Still open:
|
||||
|
||||
- the one root flake: three flakes become one, written by the agent `flake-one`; until it lands the
|
||||
nix commands in [build-and-test.md](build-and-test.md) and the flake attribute names in the scripts and
|
||||
runbooks (`.#kfde-...`, `.#kfm-...`, `legacyPackages.*.vm.NAME`) are the old ones;
|
||||
- CI and release: the workflows of the old repositories are archived, inert, in `docs/dev/old-ci/`; no
|
||||
workflow builds the Linux or macOS packages, and there is one release plan to write;
|
||||
- where the repository and the sites are published: URLs of the old projects
|
||||
(`LGUG2Z/komorebi-for-kde`, `LGUG2Z/komorebi-for-mac`, `komorebi-for-mac.lgug2z.com`, the update check of
|
||||
the macOS bar, `$schema` URLs of example configs and schemas) are unchanged;
|
||||
- `docs/linux/dev/COMPARE.md` and `scripts/linux/compare-gen.py` are stale (marked so);
|
||||
- `docs/linux/dev/ARCHITECTURE.md` and the other KDE documents were written for a KDE-only repository;
|
||||
their paths were fixed, their prose about "this repository" was not rewritten.
|
||||
|
||||
## 7. Feedback loops, from cheap to expensive
|
||||
|
||||
| Tier | What | Time | How |
|
||||
|---|---|---|---|
|
||||
| 0 | docs and links | none | nothing builds; a docs-only commit leaves every nix check a cache hit, except text under `komorebi-for-kde/` and `komorebi-for-mac/`, which are inputs of their derivations |
|
||||
| 0 | docs and links | none | nothing builds; a docs-only commit leaves every nix check a cache hit, except text under `nix/linux/` and `nix/macos/` and the sources the derivations use |
|
||||
| 1 | native Linux: `cargo check/test` of the shared crates and the KDE daemon | seconds to minutes | build-and-test.md, section 2 |
|
||||
| 2 | cross-compile and nix checks: Windows clippy, macOS type-check with a fake C compiler, KDE non-VM checks, schema and CLI oracles | minutes | build-and-test.md, sections 1 and 3 |
|
||||
| 3 | e2e: Windows QEMU scenarios, KDE VM suites (`fast`, `slow`) | tens of minutes, batched | build-and-test.md, sections 4 and 5 |
|
||||
| 4 | a real Mac | by hand | macos-handcheck.md |
|
||||
|
||||
### The helper tools (outside the repository)
|
||||
### The helper tools
|
||||
|
||||
The agents that did the consolidation used scripts that live outside the repository, in
|
||||
`/home/jado/komomono-work/tools` on the build host. They are not part of the repository. Proposal, not
|
||||
done: commit the ones that encode project knowledge under `scripts/dev/`, and leave the host-specific ones out.
|
||||
The agents that did the consolidation used these scripts. They were first kept outside the repository (at
|
||||
the time of the table below, `/home/jado/komomono-work/tools` on the build host); the cutover stack has them
|
||||
in `tools/` (see `tools/README.md`); `host-sample`, `jitter-probe` and `mini`, which are about one host, were
|
||||
left out. The table is the original assessment.
|
||||
|
||||
| Tool | What it does | Worth committing? |
|
||||
|---|---|---|
|
||||
| `fast-check` (+ its README) | runs only the checks that the touched paths need (tier 1 and 2), with persistent target dirs | yes: it is the quickest way to get the right gate for a change; needs its scratch paths made configurable (`FAST_CHECK_SCRATCH`, already an env var) |
|
||||
| `mac-check.sh` | macOS type-check through a fake C compiler | yes, merged into `fast-check` (it has hard-coded paths to a workspace) |
|
||||
| `kde-closure-check` | fails when `komorebi-for-kde/nix/root-crates.json` and the KDE cargo closure differ | yes: it protects the KDE source filter; run after any dependency change in the KDE tree or the crates it uses |
|
||||
| `kde-closure-check` | fails when `nix/linux/root-crates.json` and the KDE cargo closure differ (the script in `tools/` still reads the old path `komorebi-for-kde/nix/root-crates.json`) | yes: it protects the KDE source filter; run after any dependency change in the KDE tree or the crates it uses |
|
||||
| `lite-env` | env vars for builds without debug info | optional (one `.env` file) |
|
||||
| `gate-lock` | host-wide FIFO lock so heavy gates and timing-sensitive e2e do not overlap | host policy; commit only if more than one person shares a build host |
|
||||
| `e2e-needed` | says whether a diff touches anything the Windows e2e binaries are built from (decides whether the e2e gate is owed) | yes, next to `fast-check` |
|
||||
|
||||
Reference in new issue
Block a user