mirror of
https://github.com/LGUG2Z/komorebi.git
synced 2026-11-15 13:22:19 +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:
LGUG2Z committed
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` |
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# The consolidation of komorebi, komorebi-for-kde and komorebi-for-mac: final-state summary
|
||||
|
||||
Status (written at wip-cand8, b6f4c2ae, 2026-10-31): a summary for a maintainer who was not there.
|
||||
Status (written at wip-cand8, b6f4c2ae, 2026-10-31; sections 1, 6, 7 and 8 were brought up to date by the cutover stack, `wip-cutover`, and say so; everything else is as written then, with the paths and version numbers of that time): a summary for a maintainer who was not there.
|
||||
Gates for candidate 8 were still running when this was written; the results stated below are the ones
|
||||
that had finished, with the candidate they ran on. Companion documents: [ARCHITECTURE-UNIFIED.md](ARCHITECTURE-UNIFIED.md)
|
||||
(the map), [build-and-test.md](build-and-test.md) (commands, flakes), [macos-hand-check-plan.md](macos-hand-check-plan.md)
|
||||
@@ -19,10 +19,12 @@ per user-facing program, the platform chosen by `cfg(target_os)`.
|
||||
| `komorebi-client` | `komorebi-client/` | `src/{windows,linux,macos}.rs` behind one `Connection` |
|
||||
| `komorebi-bar` | `komorebi-bar/` | `src/windows/`, `src/macos/`; shared part in `crates/komorebi-bar-core`. KDE has no bar |
|
||||
|
||||
Three platform trees remain, because the platform layers are different code: the repository root (Windows:
|
||||
`komorebi/` is the library `komorebi-windows`), `komorebi-for-kde/` (`komorebi-linux`, hotkeys, NixOS module,
|
||||
the VM suites) and `komorebi-for-mac/` (`komorebi-macos`, nix-darwin module). The daemon libraries have no
|
||||
binary; the `komorebi` package is the binary. The crate map and the tree layout are in
|
||||
Three platform layers remain, because the platform layers are different code, each in its own directory
|
||||
since the cutover stack: `komorebi-windows/` (Windows; it was `komorebi/`), `komorebi-linux/` and
|
||||
`komorebi-hotkeys/` (KDE; with `nix/linux/`, the NixOS module and the VM suites, and `docs/linux/`) and
|
||||
`komorebi-macos/` (macOS; with `nix/macos/`, the nix-darwin module, and `docs/macos/`). The trees
|
||||
`komorebi-for-kde/` and `komorebi-for-mac/` of the first version of this summary no longer exist. The daemon
|
||||
libraries have no binary; the `komorebi` package is the binary. The crate map and the tree layout are in
|
||||
[ARCHITECTURE-UNIFIED.md](ARCHITECTURE-UNIFIED.md); how to build each is in [build-and-test.md](build-and-test.md).
|
||||
|
||||
## 2. What was shared, and how
|
||||
@@ -64,8 +66,8 @@ flattened in, pinned by tests). Native tests of the shared code run on Linux and
|
||||
|
||||
### Oracles (checked in files, compared byte for byte)
|
||||
|
||||
Wire goldens (`komorebi-protocol`), the three `schema.json` and `schema.asc.json`, the two `schema.bar.json`
|
||||
(size and hash pinned in `komorebi-bar-core`), the `docs/cli` pages of each tree, JSON pins of `Container`,
|
||||
Wire goldens (`komorebi-protocol`), the three `schema.json` and `schema.asc.json` (now `schemas/{windows,linux,macos}/`), the two `schema.bar.json`
|
||||
(size and hash pinned in `komorebi-bar-core`), the `docs/cli`, `docs/linux/cli` and `docs/macos/cli` pages (before the cutover: `docs/cli` of each tree), JSON pins of `Container`,
|
||||
`Monitor` and the state of the three daemons from real fixtures, and derivation drift (`nix eval ...drvPath`).
|
||||
Details in [ARCHITECTURE-UNIFIED.md](ARCHITECTURE-UNIFIED.md) section 5.
|
||||
|
||||
@@ -112,23 +114,25 @@ commands, now resolved for all platforms by owner decision; (2) `Monitor::focus_
|
||||
name; (3) `Workspace::remove_container` focuses the container next to the focused one rather than the removed
|
||||
one; (4) a subscriber that stops reading can stall the daemon on macOS (a 1 s write timeout was tried and reverted
|
||||
because it can truncate a notification). Items 2-4 are inherited behaviour, pinned by tests, left for a decision.
|
||||
Other open items: the Windows lock-hold stall; `komorebi-for-kde/justfile` recipes assume a KDE-only workspace;
|
||||
`docs/dev/COMPARE.md` and `scripts/compare-gen.py` are stale.
|
||||
Other open items: the Windows lock-hold stall; `docs/linux/dev/COMPARE.md` and `scripts/linux/compare-gen.py` are stale (the
|
||||
KDE-only justfile this paragraph used to name was merged into the one root `justfile` by the cutover stack).
|
||||
|
||||
## 7. Cutover list (not done)
|
||||
## 7. The cutover: done in the cutover stack, and still open
|
||||
|
||||
What must be deleted or merged to finish; nothing below was changed.
|
||||
The stack `wip-cutover` (on `wip-main`; `jj log -r 'wip-main..wip-cutover'`) did the mechanical part. Each row
|
||||
says what the first version of this section proposed and where it stands.
|
||||
|
||||
| Item | State | Action |
|
||||
| Item | State now | Open |
|
||||
|---|---|---|
|
||||
| shim packages | `komorebic-linux`, `komorebic-macos`, `komorebi-client-linux`, `komorebi-client-macos`, `komorebi-bar-macos` are `#[path]` includes of the unified modules | delete them and their directories under `komorebi-for-kde/` and `komorebi-for-mac/`; update the flakes and justfiles that name them |
|
||||
| version crates | `version-linux`, `version-macos` | one `version` crate; one workspace version (Windows 0.1.42, KDE 0.1.0, macOS 0.1.1 today) |
|
||||
| flakes | three flakes; the root one imports the other two as `kfde-*` and `kfm-*` | one flake with the platform trees moved to final directories; KDE's VM suites and module, macOS's darwin module stay as outputs |
|
||||
| `deny.toml`, `rustfmt.toml`, toolchain files | one per tree | one of each |
|
||||
| workflows | root: `windows.yaml`, `feature-check.yaml`; KDE: `ci.yaml` (nix checks, VM tiers, canary, release), `update-flake-lock.yaml`, `rerun-no-kvm.yaml`; macOS: `nix.yaml`, `release.yaml` (Homebrew formula) | a proposal, not decided: one CI that builds the three packages, runs `crates/` natively, the nix checks, the Windows e2e on a host with KVM, and the KDE VM tiers as today; one release workflow producing the Windows, Linux and macOS artifacts with one tag and one version |
|
||||
| docs | per-tree `docs/`, CONTRIBUTING, READMEs | one docs tree; `docs/cli` per platform stays until commands are merged; retire COMPARE.md |
|
||||
| justfiles | three | one |
|
||||
| tools | `tools/` is committed (fast-check, format-all, kde-closure-check, e2e-needed, gate-lock, ...); see `tools/README.md` | keep; delete the per-tree copies of what they replace |
|
||||
| shim packages | `komorebic-linux`, `komorebic-macos`, `komorebi-client-linux`, `komorebi-client-macos`, `komorebi-bar-macos` deleted | none |
|
||||
| version crates and numbers | one `crates/komorebi-version` instead of `version-linux`, `version-macos`; one workspace version, 0.2.0 (the 0.1.42 / 0.1.0 / 0.1.1 of the first version of this section are history) | none |
|
||||
| directories | `komorebi/` is `komorebi-windows/`; the KDE and macOS libraries are `komorebi-linux/` and `komorebi-macos/`; `komorebi-hotkeys/`, `spikes/` at the top level; `docs/{linux,macos}`, `nix/{linux,macos}`, `scripts/linux`, `schemas/{windows,linux,macos}` | none |
|
||||
| `deny.toml`, `rustfmt.toml`, toolchain, `.gitignore`, licence, `justfile` | one of each at the root | none |
|
||||
| docs | the READMEs and CONTRIBUTING of the ports are `docs/linux/` and `docs/macos/`; paths and links were fixed; the Windows mkdocs site excludes `docs/linux`, `docs/macos` and `docs/dev` | `docs/cli` per platform stays until the commands are merged; `docs/linux/dev/COMPARE.md` is stale and `scripts/linux/compare-gen.py` with it; the KDE documents still say "this repository" for what is now one of three |
|
||||
| flakes | the `kfde-*` and `kfm-*` flakes were still three when the directories moved (`komorebi-for-kde/flake.nix`, `komorebi-for-mac/flake.nix`) | one root flake is being written by the agent `flake-one`; the nix commands in the documents name the old attributes until it lands |
|
||||
| workflows | the files of the old repositories are in `docs/dev/old-ci/{linux,macos}/` (inert: under `docs/` GitHub does not run them); the Windows `.github/` is as it was | the proposal stands, not decided: one CI that builds the three packages, runs `crates/` natively, the nix checks, the Windows e2e on a host with KVM and the KDE VM tiers; one release workflow with one tag and one version; the Homebrew formula template and the macOS docs-site files wait in the archive |
|
||||
| URLs | unchanged | where the repository and the sites are published is not decided: the old GitHub repositories (`LGUG2Z/komorebi-for-kde`, `LGUG2Z/komorebi-for-mac`), `komorebi-for-mac.lgug2z.com`, the update check of the macOS bar, the `$schema` URLs of the example configurations and generated schemas |
|
||||
| tools | `tools/` is committed; `tools/format-all` has one group | `tools/kde-closure-check` still reads the old path of `root-crates.json` |
|
||||
|
||||
## 8. How to continue
|
||||
|
||||
@@ -145,7 +149,7 @@ What must be deleted or merged to finish; nothing below was changed.
|
||||
a real platform reason, put the difference behind a hook (as `HideSpot` and `begin_pass` do) rather than
|
||||
converging behaviour you cannot verify.
|
||||
6. **Decide items 2-4 of the known issues**, then move them into the shared code with the e2e gate.
|
||||
7. **Complete the cutover** (section 7), then regenerate the Windows `docs/cli` and the schema docs.
|
||||
7. **Finish the cutover** (the open column of section 7: the one flake, CI and releases, the URLs), then regenerate the Windows `docs/cli` and the schema docs.
|
||||
|
||||
## 9. The decisions that shaped the design
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# One `komorebi`, one `komorebic`, one `komorebi-bar`
|
||||
|
||||
> **Status (wip-cand4):** steps 0-8 done: one `komorebi` (`komorebi-daemon/`), `komorebic`, `komorebi-client` and `komorebi-bar` package, platform by `cfg(target_os)`; the cutover (shim packages, one flake, final directories, one version) is open. The older sections below are history: in particular the note "never write `-p komorebi`" was true before step 8 and is wrong now; see [build-and-test.md](build-and-test.md) for current commands.
|
||||
> **Status (the cutover stack, `wip-cutover`):** steps 0-8 done: one `komorebi` (`komorebi-daemon/`), `komorebic`, `komorebi-client` and `komorebi-bar` package, platform by `cfg(target_os)`; the cutover (shim packages deleted, final directories, one version 0.2.0) is done too; the one flake, CI and releases are open (see "What is left for the cutover" at the end). The older sections below are history and keep the names and paths of their time (`komorebic-linux`, `komorebi-for-kde/`, `komorebi-for-mac/`, `version-linux`, the versions 0.1.42 / 0.1.0 / 0.1.1, `kfde-*`/`kfm-*` flake attributes): in particular the note "never write `-p komorebi`" was true before step 8 and is wrong now; see [build-and-test.md](build-and-test.md) for current commands. Where the old directories were: `komorebi/` is now `komorebi-windows/`, `komorebi-for-kde/komorebi/` is `komorebi-linux/`, `komorebi-for-mac/komorebi/` is `komorebi-macos/`, the KDE and macOS docs, nix files and scripts are under `docs/`, `nix/` and `scripts/` in `linux/` and `macos/` subdirectories, and the schemas are in `schemas/{windows,linux,macos}/`.
|
||||
|
||||
Goal: three packages and three binaries that build on Windows, KDE (Linux) and macOS, the platform
|
||||
chosen by `cfg(target_os)` (generics, `cfg_select!`, exhaustive `match`; no macros as a design tool).
|
||||
@@ -147,7 +147,7 @@ by hand: 4, 7, 8, 9.
|
||||
Mac hand check (type-check proves none of it): `komorebic --version` and `--help` show the macOS
|
||||
command set and the name `komorebic`; `komorebic start` finds and starts `komorebi`, `stop` stops it;
|
||||
`komorebic docgen` unchanged; `komorebi --version`; the daemon starts, tiles and `komorebic state`
|
||||
answers; `komorebi-bar` opens, `--schema` equals `komorebi-for-mac/schema.bar.json`;
|
||||
answers; `komorebi-bar` opens, `--schema` equals `komorebi-for-mac/schema.bar.json` [now `schemas/macos/schema.bar.json`];
|
||||
the embedded `applications.json` is the macOS one;
|
||||
`otool -L` of each binary lists no Windows or Linux-only library.
|
||||
|
||||
@@ -313,18 +313,18 @@ Run on the revisions of `wip-u-pkg-mig` at or after the stated one, from the rep
|
||||
|
||||
```
|
||||
cargo build --locked -p komorebic -p komorebi-macos -p komorebi-bar # after "one komorebi-bar package"
|
||||
cargo build --locked -p komorebic-macos -p komorebi-bar-macos -p komorebi-client-macos # the shims still build
|
||||
# (the line that built the shims komorebic-macos, komorebi-bar-macos, komorebi-client-macos is gone: they were deleted)
|
||||
cargo clippy --locked -p komorebic -p komorebi-client -p komorebi-bar -p komorebi-bar-core -p komorebi-macos --all-targets -- -D warnings
|
||||
cargo test --locked -p komorebi-macos -p komorebic -p komorebi-client -p komorebi-bar-core -p komorebi-bar
|
||||
target/debug/komorebic --help; target/debug/komorebic --version; target/debug/komorebic docgen --output /tmp/docs-mac
|
||||
target/debug/komorebi-bar --schema | cmp - komorebi-for-mac/schema.bar.json
|
||||
target/debug/komorebi-bar --schema | cmp - schemas/macos/schema.bar.json
|
||||
```
|
||||
|
||||
Note: there is no package named `komorebi` yet: the daemon is `komorebi-macos` on macOS and `komorebi-windows` on Windows (binary name `komorebi` for both; the single `komorebi` package is step 8). Never write `-p komorebi`. Do not build `komorebic` and `komorebic-macos` in the same command (same binary name). The lint fix `fix(bar-core): WidgetConfig::supported as matches!` is needed for clippy to pass.
|
||||
Note: there is no package named `komorebi` yet: the daemon is `komorebi-macos` on macOS and `komorebi-windows` on Windows (binary name `komorebi` for both; the single `komorebi` package is step 8). Never write `-p komorebi` (history: step 8 below added it). The `komorebic-macos` shim no longer exists. The lint fix `fix(bar-core): WidgetConfig::supported as matches!` is needed for clippy to pass.
|
||||
The macOS checks that matter by revision:
|
||||
`refactor(komorebic): move the macOS CLI ...` (komorebic, quickstart, start, stop), `refactor(client): one
|
||||
komorebi-client ...` (the client tests in `komorebi-client/src/macos.rs`), and `refactor(bar): one
|
||||
komorebi-bar package ...` (the bar opens, `--schema`). Everything in `docs/dev/macos-handcheck.md` still applies.
|
||||
komorebi-bar package ...` (the bar opens, `--schema`). Everything in `docs/dev/macos-handcheck.md` still applies. (The commands in this block are those of the time; the runbook with the current names is `docs/dev/macos-hand-check-plan.md`.)
|
||||
|
||||
## Step 8 done: one `komorebi`
|
||||
|
||||
@@ -337,18 +337,31 @@ files are `daemon.rs` of those libraries (`komorebi::` became `crate::`), and th
|
||||
The KDE tests that run the binary moved to `komorebi-daemon/tests/linux_*.rs`.
|
||||
|
||||
So `cargo build -p komorebi`, `-p komorebic`, `-p komorebi-bar` and `cargo run -p komorebi-bar -- --schema` build and
|
||||
run the right program on Windows, KDE Plasma and macOS. What is left for the cutover (nothing here deletes it yet):
|
||||
run the right program on Windows, KDE Plasma and macOS.
|
||||
|
||||
### What is left for the cutover
|
||||
|
||||
Done in the cutover stack (`jj log -r 'wip-main..wip-cutover'`):
|
||||
|
||||
- the shim packages `komorebic-linux`, `komorebic-macos`, `komorebi-client-linux`, `komorebi-client-macos`,
|
||||
`komorebi-bar-macos` (each a `#[path]` include of the unified module) and their directories under
|
||||
`komorebi-for-kde/` and `komorebi-for-mac/`;
|
||||
- the per-platform `version` packages (`version-linux`, `version-macos`) once one `version` crate serves
|
||||
all three;
|
||||
- the three flakes becoming one, the repository layout (`komorebi-for-kde/`, `komorebi-for-mac/` trees move
|
||||
under the platform crates' final directories), one `deny.toml`, the workspace-wide version number
|
||||
(0.1.42 / 0.1.0 / 0.1.1), and the comments and docs that name the old paths;
|
||||
`komorebi-bar-macos` and their directories are deleted;
|
||||
- `version-linux` and `version-macos` are one `crates/komorebi-version`; the workspace version is 0.2.0 for
|
||||
every package (0.1.42 / 0.1.0 / 0.1.1 above are history);
|
||||
- the directories are the final ones (`komorebi-windows/`, `komorebi-linux/`, `komorebi-macos/`,
|
||||
`komorebi-hotkeys/`; `docs/{linux,macos}`, `nix/{linux,macos}`, `scripts/linux`, `schemas/*`), one `deny.toml`,
|
||||
`rustfmt.toml`, `rust-toolchain.toml`, `.gitignore`, `LICENSE.md` and `justfile`, and the comments and
|
||||
docs that named the old paths name the new ones;
|
||||
- the libraries `komorebi-windows`, `komorebi-linux`, `komorebi-macos` stay: they are the daemons.
|
||||
|
||||
Still open:
|
||||
|
||||
- the three flakes becoming one: being written by the agent `flake-one`; the `kfde-*` and `kfm-*` attribute
|
||||
names in this file are the old ones until it lands;
|
||||
- CI and release workflows: the old repositories' files are archived in `docs/dev/old-ci/` and nothing
|
||||
builds the Linux or macOS packages in CI;
|
||||
- the site and repository URLs of the old projects, which are unchanged;
|
||||
- `docs/linux/dev/COMPARE.md` and `scripts/linux/compare-gen.py` are stale.
|
||||
|
||||
Owed by the coordinator for this step (none was built): the heavy builds listed above, now also
|
||||
`nix build -L .#packages.x86_64-linux.komorebi .#packages.x86_64-linux.kfde-komorebi`; the Windows e2e
|
||||
(BEHAVIOUR: the Windows executable is linked from the library's `daemon::run`); the KDE VM `fast` suites.
|
||||
@@ -357,7 +370,7 @@ Owed by the coordinator for this step (none was built): the heavy builds listed
|
||||
|
||||
```
|
||||
cargo build --locked -p komorebi -p komorebic -p komorebi-bar
|
||||
target/debug/komorebi --version # prints komorebi 0.1.0 (the macOS version crate)
|
||||
target/debug/komorebi --version # prints komorebi 0.2.0 (it printed 0.1.0 at the time of step 8)
|
||||
target/debug/komorebi --help | head -3
|
||||
cargo clippy --locked -p komorebi -p komorebi-macos -p komorebic -p komorebi-client -p komorebi-bar -p komorebi-bar-core --all-targets -- -D warnings
|
||||
cargo test --locked -p komorebi-macos -p komorebic -p komorebi-client -p komorebi-bar-core -p komorebi-bar
|
||||
|
||||
Reference in new issue
Block a user