You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
- Remove Omarchy distribution support (directory was already deleted)
- Remove generic/github-add-key script and references (SSH keys handled during auth)
- Remove generic/lazyvim script (already deleted, cleaning up references)
- Fix scripts/check.sh to exclude markdown files from bash syntax checks
- Update copilot-instructions.md to reflect current state and resolved issues
Copy file name to clipboardExpand all lines: .github/copilot-instructions.md
+82-12Lines changed: 82 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,15 +10,19 @@ Because scripts are sourced (not executed in a subshell) they run in the current
10
10
11
11
## Project structure and conventions
12
12
13
-
-`bootstrap` (top-level): dispatches to a distro directory after reading `/etc/os-release`.
13
+
-`bootstrap` (top-level): dispatches to a distro directory after reading `/etc/os-release`. Supports Ubuntu, Pop!_OS, Fedora, and Arch.
14
14
-`*/bootstrap` (per-distro): orchestrates other scripts in that distro folder and the shared `generic/` helpers.
15
-
-`generic/`: small reusable steps (create-ssh-key, install-jetbrains-tools, install-zsh-customizations, lazyvim, etc.). Treat these as library modules that are `source`d by distro bootstrappers.
15
+
-`generic/`: small reusable steps (create-ssh-key, install-jetbrains-tools, install-zsh-customizations, github-auth-login/logout, add-user-to-groups, create-directories, homebrew). Treat these as library modules that are `source`d by distro bootstrappers.
16
16
-`*/*install-*-packages` files: contain package lists and package-manager-specific commands (apt, dnf, pacman, yay). Be careful when modifying package sets — keep package-manager flags and ordering intact.
17
+
-`test/`: contains Docker and QEMU testing infrastructure for validation (primarily for Ubuntu).
18
+
-`scripts/`: helper scripts like `check.sh` for local syntax and shellcheck validation.
19
+
-`Makefile`: provides convenient targets for testing, linting, and building test images.
17
20
18
21
Examples to reference when changing behavior:
19
22
- Distribution detection: `bootstrap` (reads `/etc/os-release` and branches on `ID`).
- Ubuntu interactive flow: `ubuntu/bootstrap` (prompts with `read -p` and conditionally runs dev/desktop/media installs).
25
+
- Fedora/Pop!_OS flow: similar interactive prompts for optional component installation.
22
26
23
27
## Interaction & side-effects to watch for
24
28
@@ -31,26 +35,92 @@ Examples to reference when changing behavior:
31
35
- Preserve the `source <(curl -fsSL ...)` style where callers expect that pattern. If you introduce an alternate execution method, add a usage comment and keep backward compatibility.
32
36
- When modifying package lists, keep package-manager specific flags (e.g., `--needed` for `pacman`, `-y`/`-qq` for `apt`) and preserve any pre-update steps (e.g., `apt-get update`).
33
37
- Reuse `generic/` helpers rather than duplicating logic across distros.
38
+
- The `lazyvim` generic helper has been removed — LazyVim setup was previously auto-installed but is no longer part of the bootstrap process.
34
39
35
40
## Testing and validation (how to be productive quickly)
36
41
37
-
- Quick lint: run `bash -n <script>` to check syntax.
38
-
- Static checks: run `shellcheck` (recommended) on changed scripts.
39
-
- Safe manual test: start a disposable VM or container for the target distribution and run the top-level `source <(...)` or the distro `bootstrap` directly.
42
+
### Local validation
40
43
41
-
## Known issues and fragile areas (observations you can trust)
44
+
Run the local validation script to check for bash syntax errors and shellcheck issues:
42
45
43
-
- The top-level `bootstrap` contains a malformed `elif` for the `arch` branch (missing spacing around `[[`), and `pop_os/bootstrap` contains a garbled line in the optical-disc install section. Be conservative when editing these lines — tests and a VM run are recommended.
46
+
```sh
47
+
bash scripts/check.sh
48
+
```
49
+
50
+
This script:
51
+
- Finds all bash scripts (files with a bash shebang).
52
+
- Runs `bash -n` to check for syntax errors.
53
+
- Runs ShellCheck to report style and correctness issues (errors only).
54
+
- Suggests installation steps if ShellCheck is not available.
55
+
56
+
You can also use the Makefile targets:
57
+
58
+
```sh
59
+
make lint # Run shellcheck on all scripts
60
+
make test-syntax # Run bash -n syntax checks
61
+
make test# Run automated Docker tests (Ubuntu)
62
+
make test-all # Test all Ubuntu versions (24.04, 25.10)
63
+
```
64
+
65
+
### Docker testing (Ubuntu)
66
+
67
+
Quick Docker-based testing for package installation validation:
68
+
69
+
```sh
70
+
# Interactive testing
71
+
make test-interactive
72
+
73
+
# Automated testing
74
+
make test
75
+
76
+
# Test all Ubuntu versions
77
+
make test-all
78
+
```
79
+
80
+
See `test/README.md` for detailed Docker and QEMU testing instructions.
81
+
82
+
### CI checks
83
+
84
+
GitHub Actions automatically run on push/PR:
85
+
-`.github/workflows/ci.yml`: runs bash syntax checks and ShellCheck on all shell scripts
Both workflows use ShellCheck with `--severity=error` (warnings are advisory, errors block merge).
89
+
90
+
## Known issues and gaps (observations you can trust)
91
+
92
+
-**Arch bootstrap incomplete**: The `arch/bootstrap` file is sparse and noted in the README as "not fully baked yet".
44
93
45
94
## What to commit and why
46
95
47
96
- Keep commits small and focused: package list changes, distribution-specific fixes, or refactors of `generic/` helpers.
48
97
- When adding non-interactive automation, add a clearly marked `_noninteractive` variant or a flag guarded by an environment variable so the interactive default remains for humans.
98
+
- Run `bash scripts/check.sh` before committing to catch syntax errors and shellcheck issues.
99
+
- For Ubuntu changes, consider running `make test` to validate changes in Docker.
49
100
50
101
## Where to look next (files that exemplify common tasks)
If any section is unclear or you'd like the file to be more prescriptive (for example adding linting CI or a non-interactive test harness), tell me which area to expand and I will iterate.
103
+
### Core entry points
104
+
-`bootstrap` (root): distribution detection and routing
If any section is unclear or you'd like the file to be more prescriptive (for example adding specific debugging techniques or extending CI capabilities), tell me which area to expand and I will iterate.
0 commit comments