docs: add comprehensive flake-parts + full dendritic migration playbook#17
docs: add comprehensive flake-parts + full dendritic migration playbook#17
Conversation
sygint
commented
Jan 20, 2026
sygint
commented
- Detailed step-by-step playbook (576 lines) covering:
- Flake-parts migration from manual outputs
- Complete dendritic pattern (merge system+home features)
- Testing & validation procedures
- Rollback plan
- Quick reference guide (205 lines) for day-to-day usage
- Feature module template for creating new features
- Estimated timeline: 6-9 hours (can be done incrementally)
- Detailed step-by-step playbook (576 lines) covering: - Flake-parts migration from manual outputs - Complete dendritic pattern (merge system+home features) - Testing & validation procedures - Rollback plan - Quick reference guide (205 lines) for day-to-day usage - Feature module template for creating new features - Estimated timeline: 6-9 hours (can be done incrementally)
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive documentation for migrating to flake-parts and implementing the full dendritic pattern for NixOS configuration management. The documentation guides users through restructuring their flake from manual outputs to a modular flake-parts system, while unifying system and home-manager configurations into single feature modules.
Changes:
- Added feature module template showing the dendritic pattern (system + home config in one file)
- Created quick reference guide with common commands and patterns for day-to-day usage
- Added detailed 576-line migration playbook with step-by-step instructions, testing procedures, and rollback plan
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 11 comments.
| File | Description |
|---|---|
modules/features/_template.nix |
Template showing standard dendritic pattern for unified feature modules with system and home-manager configuration |
docs/FLAKE-PARTS-QUICK-REFERENCE.md |
Quick reference guide for common commands, patterns, and troubleshooting |
docs/FLAKE-PARTS-DENDRITIC-PLAYBOOK.md |
Comprehensive migration playbook with phases, testing, and rollback procedures |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| inputs = { | ||
| flake-parts.url = "github:hercules-ci/flake-parts"; | ||
| nixpkgs.url = "github:nixos/nixpkgs?shallow=1&ref=nixos-unstable"; | ||
| # ... all your existing inputs |
There was a problem hiding this comment.
The comment "... all your existing inputs" is vague in documentation that's meant to be a detailed playbook. Consider either listing the specific inputs that should be included here (based on the actual flake inputs), or providing a clearer reference to where users can find their existing inputs to copy.
| # ... all your existing inputs | |
| # Copy the rest of your existing inputs from your current flake.nix | |
| # (for example: home-manager, flake-utils, nixpkgs-stable, etc.) |
| self.nixosConfigurations.orion; | ||
| }; | ||
| }; | ||
| # ... other systems |
There was a problem hiding this comment.
The comment "... other systems" leaves users without guidance on how to structure additional systems. For a comprehensive playbook, either show the complete structure for at least one more system, or provide a clear template pattern that users should follow.
| # ... other systems | |
| vega = { | |
| hostname = "vega"; | |
| profiles.system = { | |
| user = "root"; | |
| path = inputs.deploy-rs.lib.x86_64-linux.activate.nixos | |
| self.nixosConfigurations.vega; | |
| }; | |
| }; |
| description = "Default terminal emulator"; | ||
| }; | ||
|
|
||
| # ... other options |
There was a problem hiding this comment.
The comment "... other options" is too vague. Since this is meant as a template/example in a detailed playbook, it would be more helpful to show 1-2 additional concrete option examples that users might commonly need for a window manager feature.
| # ... other options | |
| animationsEnabled = lib.mkOption { | |
| type = lib.types.bool; | |
| default = true; | |
| description = "Whether to enable Hyprland animations by default."; | |
| }; | |
| extraConfig = lib.mkOption { | |
| type = lib.types.lines; | |
| default = ""; | |
| description = "Additional Hyprland configuration to append to the generated config."; | |
| }; |
| settings = { | ||
| # Use cfg options here | ||
| "$terminal" = cfg.terminal; | ||
| # ... rest of hyprland config |
There was a problem hiding this comment.
The comment "... rest of hyprland config" is too vague for a playbook meant to guide users through migration. Consider showing at least a few more key settings to give users a better sense of what belongs here.
| # ... rest of hyprland config | |
| # Example core Hyprland settings | |
| monitor = [ | |
| "eDP-1,1920x1080@60,0x0,1" | |
| ]; | |
| general = { | |
| gaps_in = 5; | |
| gaps_out = 20; | |
| border_size = 2; | |
| "col.active_border" = "rgba(33ccffee)"; | |
| "col.inactive_border" = "rgba(595959aa)"; | |
| }; | |
| input = { | |
| kb_layout = "us"; | |
| follow_mouse = 1; | |
| touchpad = { | |
| natural_scroll = true; | |
| }; | |
| }; | |
| # Basic keybinds (use $terminal from cfg) | |
| bind = [ | |
| "SUPER, Return, exec, $terminal" | |
| "SUPER, Q, killactive," | |
| "SUPER, F, togglefloating," | |
| ]; |
| # Hyprland scripts | ||
| "hypr/scripts/monitor-handler.sh".source = | ||
| ./../../systems/${config.networking.hostName}/scripts/monitor-handler.sh; | ||
| # ... |
There was a problem hiding this comment.
The ellipsis "..." comment is not helpful. Either show one more concrete example of additional config files that would typically be needed, or remove this comment.
| # ... | |
| "hypr/hyprland.conf".source = | |
| ./../../systems/${config.networking.hostName}/hypr/hyprland.conf; |
| - ✅ Using `flake-parts` for modular flake composition | ||
| - ✅ Unified feature modules in `modules/features/` | ||
| - ✅ One file per feature with system + home config | ||
| - ✅ Consistent enable options: `modules.<feature>.enable` |
There was a problem hiding this comment.
The option naming pattern shown here as modules.<feature>.enable is inconsistent with the rest of the document, which uses modules.features.<feature>.enable (note the missing "features" namespace). This should be modules.features.<feature>.enable to match the actual implementation shown throughout the document.
| - ✅ Consistent enable options: `modules.<feature>.enable` | |
| - ✅ Consistent enable options: `modules.features.<feature>.enable` |
| fh = inputs.fh.packages.x86_64-linux; | ||
| }; | ||
| modules = [ | ||
| ./systems/orion/default.nix |
There was a problem hiding this comment.
The module path ./systems/orion/default.nix should be relative to the flake root or use an absolute path from the flake root. In the context of flake-modules/nixos-configurations.nix, this path would need to be ../systems/orion/default.nix or ${self}/systems/orion/default.nix to be correct.
| ./systems/orion/default.nix | |
| ../systems/orion/default.nix |
| modules = [ | ||
| ./systems/orion/default.nix | ||
| inputs.home-manager.nixosModules.home-manager | ||
| # ... other common modules |
There was a problem hiding this comment.
The comment "... other common modules" is too vague for a detailed playbook. Users need to know what modules should be included here. This should either list the specific common modules (like the system modules, home-manager configuration, etc.) or provide a clear reference to where these can be found.
| # ... other common modules | |
| # Common modules shared across all hosts: | |
| ./modules/system/common.nix | |
| ./modules/system/security.nix | |
| ./modules/system/networking.nix | |
| ./modules/system/users.nix |
| hyprlock | ||
| hypridle | ||
| hyprpicker | ||
| # ... other system packages |
There was a problem hiding this comment.
The comment "... other system packages" doesn't provide enough guidance. For a playbook example, showing 2-3 more concrete packages would help users understand what typically belongs here versus in user packages.
| # ... other system packages | |
| seatd | |
| xdg-desktop-portal-hyprland | |
| wayland-utils |
| # User-level packages | ||
| rofi-wayland | ||
| waybar | ||
| # ... |
There was a problem hiding this comment.
The ellipsis "..." comment is not helpful in documentation. Either show more concrete examples of additional packages that would typically be included, or remove this comment.
1 participant
