starred/nix-config-ryan4yin
1
0 Fork 0
mirror of https://github.com/ryan4yin/nix-config.git synced 2026-11-13 12:13:36 +01:00
Code Issues Packages Projects Releases 10 Wiki Activity

docs: add a workaround registry with removal conditions

Browse Source 
WORKAROUNDS.md collects temporary workarounds, version pins, carried patches, and known gaps, each with a removal condition, so they can be re-evaluated and rolled back on a schedule. AGENTS.md points to it and states the convention: a change that adds a workaround adds a row in the same PR.
This commit is contained in:
Ryan Yin committed 2026-10-03 12:53:30 +08:00
1 parent 0a847c1f55
commit e975f69383
2 files changed
+56
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

AGENTS.md
+7
View File
@@ -59,6 +59,12 @@ deployments. Keep repository guidance here; reusable global rules live in `agent
- Use `lib.mkDefault` for defaults and `lib.mkForce` only when necessary.
- Give module options a `description` and preserve platform-specific conditions.
## Workarounds
Temporary workarounds, version pins, carried patches, and known gaps are recorded in
[WORKAROUNDS.md](./WORKAROUNDS.md), each with a removal condition. Add a row in the same change that
introduces one, and re-evaluate entries when their `Revisit` trigger comes up.
## Command Hazards
- `just eval-host <host>`, `just build-host <host>`, `just build-microvm <guest>`, and `just test`
@@ -120,6 +126,7 @@ repository, and cross-link them — no need to be told.
## Further Context
- [Repository overview](./README.md)
- [Workarounds & known gaps](./WORKAROUNDS.md)
- [Outputs and tests](./outputs/README.md)
- [Hosts](./hosts/README.md), [system modules](./modules/README.md), and
[Home Manager](./home/README.md)
WORKAROUNDS.md
+49
View File
@@ -0,0 +1,49 @@
# Workarounds & known gaps
Temporary workarounds, version pins, carried patches, and known gaps are collected here, each with
the condition under which it can be removed. Review the list periodically so obsolete workarounds
get rolled back instead of lingering.
## How to use
- **Adding** — a change that introduces a workaround, pin, carried patch, or known gap adds a row
here in the same PR, with a concrete **removal condition**.
- **Removing** — once the removal condition is met, delete the change and set `Status` to `removed`
(mention the ID in the commit), or delete the row.
- **Reviewing** — re-evaluate rows whose `Revisit` trigger is due and refresh `Status`.
## Types
| Type | Meaning |
| ------------- | --------------------------------------------------------------------------- |
| `patch` | Upstream code carried locally (an overlay, a patch file, or a fork branch). |
| `pin` | A version or revision pinned for a reason that can go away. |
| `workaround` | A setting that works around a bug or a hardware quirk. |
| `known-issue` | A known limitation with no fix yet. |
| `wip` | An unfinished feature or gap. |
## Registry
| ID | Type | What & where | Why | Removal condition | Added | Revisit | Status |
| ------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------------------------------------------- | ------ |
| WA-001 | `pin` | smartctl_exporter pinned to upstream `6274decc`, which carries PR [#329](https://github.com/prometheus-community/smartctl_exporter/pull/329) — `overlays/smartctl-exporter/` | `/metrics` returns HTTP 500 once a device becomes readable after startup ([#305](https://github.com/prometheus-community/smartctl_exporter/issues/305), [#326](https://github.com/prometheus-community/smartctl_exporter/issues/326)) | Drop once smartctl_exporter **0.15.0** is released and packaged in nixpkgs | 2026-10-03 | next nixpkgs bump | active |
| WA-002 | `pin` | `nixpkgs-2505` — `flake.nix`, consumer `home/base/tui/container.nix` | `kubernetes-helm` regressed in newer nixpkgs | Drop the input and its consumer once helm works again in current nixpkgs | 2025-12-03 | when helm is revisited | active |
| WA-003 | `pin` | `rust-overlay` follow — `flake.nix` | lanzaboote v1.1.0's pinned rust-overlay uses the deprecated `stdenv.isLinux`/`stdenv.isDarwin` | Drop the follow once lanzaboote updates its pin (or we drop the lanzaboote pin) | 2026-09-25 | on lanzaboote bump | active |
| WA-004 | `pin` | `catppuccin` on `main` — `flake.nix` | `main` carries the nodejs→nodejs-slim deprecation fix, which is not in a release | Switch to a release tag once it includes the fix | 2026-09-25 | on catppuccin release | active |
| WA-005 | `pin` | `tuios` input — `flake.nix`, `home/base/tui/tuios/` | nixpkgs lags behind upstream | Use nixpkgs' `tuios` once it is recent enough | 2026-10-03 | on nixpkgs bump | active |
| WA-006 | `pin` | `nixpkgs-blender` — `flake.nix` | Blender 5.2 LTS + CUDA/OptiX pin; keeps `just up` from triggering a full source rebuild | Bump deliberately when needed; drop the pin if the current nixpkgs build is acceptable | 2026-07-24 | deliberate | active |
| WA-007 | `pin` | WeChat from `nixpkgs-master` — `hardening/bwraps/default.nix` | newest builds; the pinned channel lags | Fall back to the stable channel once it has a good build | 2026-10-03 | on nixpkgs bump | active |
| WA-008 | `workaround` | Relaxed NVMe APST (`nvme_core.default_ps_max_latency_us=100000`) — `hosts/idols-ai/hardware-configuration.nix` | the KINGBANK KP260 (DRAM-less QLC) froze on slow APST wake-ups | Keep relaxed while kernel logs stay clean; restore `nvme_core.default_ps_max_latency_us=0 nvme_core.io_timeout=4294967295 pcie_aspm=off` if freezes return | 2026-10-03 | watch NVMe timeout/reset/AER in the journal | active |
| WA-009 | `workaround` | USB-SATA bridge mitigations (`usbcore.autosuspend=-1`, `usb-storage.delay_use=10`) — `hosts/12kingdoms-youko/default.nix` | flaky JMicron JMS567 resets with UDMA-CRC and I/O errors | Drop once the bridge/controller is replaced; the signal is smartctl CRC/media errors | 2026-09-21 | on hardware change or CRC errors | active |
| WA-010 | `workaround` | Insta360 Link USB reset on S3 resume — `hosts/idols-ai/default.nix` | the camera stays enumerated with a stalled UVC endpoint after resume | Drop after the Insta360 firmware or the kernel `uvcvideo` fixes it | 2026-08-01 | on kernel or firmware change | active |
| WA-011 | `workaround` | Kernel module blacklist (`esp4`, `esp6`, `rxrpc`) — `modules/nixos/base/kernel-hardening.nix` | attack surface for the Dirty Frag LPE (CVE-2026-43284 / CVE-2026-43500) | Kept as defence in depth; drop only if something needs those modules | 2026-10-03 | rarely | active |
| WA-012 | `known-issue` | Apple Silicon 16k page size — `hosts/12kingdoms-shoukei/apple-silicon.nix` | some x86_64 apps and games need `muvm`, which is currently disabled | Hardware limitation; revisit when Asahi or muvm support changes | — | on Asahi changes | active |
| WA-013 | `wip` | NixOS tests — `outputs/README.md` | tests rebuild custom packages (no private cache) and hosts need their own ssh host key to decrypt agenix | Resolve when a private cache exists and tests can run per-service | 2024-03-13 | quarterly | active |
## Related
- Unmerged **nixpkgs** PRs are carried via the `nixpkgs-patched` input and the
[`.agents/skills/nixpkgs-patched`](./.agents/skills/nixpkgs-patched/SKILL.md) workflow (that input
currently carries nothing; the `patch` rows above are per-package overlays instead).
- Routine version pins (colmena, agenix, disko, lanzaboote, haumea, home-manager, `nixpkgs-stable`,
`nixpkgs-darwin`, …) are the versions in use, not workarounds, so they are not listed here.