diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..027eb9e --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,42 @@ +# Guidance for coding agents + +This repository is documentation only. There is no application code here. + +## Ground rules + +- Do not invent behavior. Verify every technical claim against the actual + repository before writing it. If you cannot verify it, say so or omit it. +- Distinguish the target from the current state. Mark aspirational rules as + goals and point at [REPOS.md](REPOS.md) for what each repo does today. +- Keep docs as the single source of truth. Do not duplicate the same guidance + across files; link instead. +- Prefer editing an existing file over adding a new one. + +## Writing + +- All docs are Markdown with the `.md` extension, lowercase. +- Follow [style/README_STANDARDS.md](style/README_STANDARDS.md): Title Case + headings, fenced code blocks with a language hint, neutral tone. +- Use relative links for files in this repo and full URLs for everything else. + When you rename a file, update every link to it (grep for the old name). +- Keep the tables in [README.md](README.md), [workflow/README.md](workflow/README.md), + and [style/README.md](style/README.md) in sync with the files on disk. + +## CI and lint + +- `shellcheck` covers tracked shell scripts (`install.sh`). +- `actionlint` covers `.github/workflows/`. +- Run both before committing; see [style/WORKFLOW.md](style/WORKFLOW.md). + +## Git + +- PRs target `main`. +- One concern per PR. +- Use conventional commit subjects (`docs:`, `ci:`, `fix:`, `chore:`). + +## Keeping REPOS.md current + +`REPOS.md` is a snapshot of the other repositories. When you change a documented +convention or a repo changes its branch, packaging, tooling, or license, update +the matching row and, if the change resolves a deviation, move or remove that +entry under "Deviations from target". diff --git a/README.md b/README.md index 187c97f..e3cd5c0 100644 --- a/README.md +++ b/README.md @@ -54,7 +54,7 @@ curl -vfSL http://wlanpi.us/install | sudo bash | [Anti-patterns](style/ANTIPATTERNS.md) | Common mistakes to avoid | | [Debchange](style/DCH.md) | Changelog formatting | | [Developer Workflow](style/WORKFLOW.md) | Development process standards | -| [Manpages](style/MANPAGES.MD) | Creating and generating manpages for WLAN Pi applications | +| [Manpages](style/MANPAGES.md) | Creating and generating manpages for WLAN Pi applications | ### Workflow @@ -64,7 +64,7 @@ curl -vfSL http://wlanpi.us/install | sudo bash | [IDE Setup](workflow/ide.md) | IDE configuration | | [Developing on Windows](workflow/dev-on-windows.md) | Windows/WSL development guide | | [Update from Dev Branch](workflow/update-from-dev.md) | Testing dev packages | -| [VSC Remote-SSH](workflow/VSC_64bit_kernel_and_32bit_userland.md) | VS Code troubleshooting | +| [VSC Remote-SSH](workflow/archive/VSC_64bit_kernel_and_32bit_userland.md) | VS Code troubleshooting (archived) | ### Licensing diff --git a/architecture/PACKAGING.md b/architecture/PACKAGING.md index 3e008c8..29be68f 100644 --- a/architecture/PACKAGING.md +++ b/architecture/PACKAGING.md @@ -199,23 +199,6 @@ Before submitting: 3. Service runs: `sudo systemctl status wlanpi-yourapp` 4. Application works: `wlanpi-yourapp --help` -## OSS attribution - -If your package relies on other open source projects, document them in `OSS.md` at the repository root: - -```markdown -# Open Source Attribution - -## Dependencies - -- library-name (License): Description - - Source: https://github.com/user/repo - -## Included Assets - -- Asset name (License): Description -``` - ## References - [Packaging Example](../PACKAGING_EXAMPLE.md) - Complete walkthrough with code diff --git a/style/MANPAGES.MD b/style/MANPAGES.md similarity index 100% rename from style/MANPAGES.MD rename to style/MANPAGES.md diff --git a/style/README.md b/style/README.md index 0447b2f..ebec3b8 100644 --- a/style/README.md +++ b/style/README.md @@ -6,7 +6,7 @@ - [Contributing](../CONTRIBUTING.md) - [Debchange](DCH.md) - [Developer Workflow](WORKFLOW.md) -- [Manpages](MANPAGES.MD) +- [Manpages](MANPAGES.md) - [Packaging](../architecture/PACKAGING.md) - [Python](PYTHON.md) - [README Standards](README_STANDARDS.md) diff --git a/workflow/README.md b/workflow/README.md index 80620f2..01b684d 100644 --- a/workflow/README.md +++ b/workflow/README.md @@ -9,5 +9,11 @@ Development environment guides and platform-specific setup for WLAN Pi contribut | [Development Setup](development-setup.md) | Setting up a local development environment | | [IDE Selection](ide.md) | Editor and IDE options for WLAN Pi development | | [Developing on Windows](dev-on-windows.md) | Line ending and Git configuration for Windows | -| [VSC Remote-SSH Troubleshooting](VSC_64bit_kernel_and_32bit_userland.md) | Fixing VSC on arm64 kernel with 32-bit userland | | [Update from Dev Branch](update-from-dev.md) | Updating a WLAN Pi device from the Packagecloud dev branch | + +## Archived + +| Document | Purpose | +|----------|---------| +| [VSC Remote-SSH Troubleshooting](archive/VSC_64bit_kernel_and_32bit_userland.md) | Fixing VSC on the old arm64-kernel/armhf-userland images | + diff --git a/workflow/VSC_64bit_kernel_and_32bit_userland.md b/workflow/archive/VSC_64bit_kernel_and_32bit_userland.md similarity index 94% rename from workflow/VSC_64bit_kernel_and_32bit_userland.md rename to workflow/archive/VSC_64bit_kernel_and_32bit_userland.md index e1dc4a7..a2790ad 100644 --- a/workflow/VSC_64bit_kernel_and_32bit_userland.md +++ b/workflow/archive/VSC_64bit_kernel_and_32bit_userland.md @@ -1,5 +1,9 @@ # Visual Studio Code (VSC) Remote-SSH Installation Troubleshooting +> **Archived.** This workaround applies to the old arm64-kernel/armhf-userland +> WLAN Pi images. Current images are arm64, so it is kept for historical +> reference only. + ## Seeing `node not found` or VSC not launching in the Remote-SSH session? Something like this during install: diff --git a/workflow/dev-on-windows.md b/workflow/dev-on-windows.md index 98c6f25..40472dd 100644 --- a/workflow/dev-on-windows.md +++ b/workflow/dev-on-windows.md @@ -14,21 +14,21 @@ The best approach is to force the use of `LF` line endings via the git environme # global parameters to force all projects to use LF line endings # list current settings -git confg --global -l +git config --global -l # set line endings git config --global core.autocrlf "false" git config --global core.eol "lf" # list new settings -git confg --global -l +git config --global -l ``` ``` # local parameters to force a specific project to use LF line endings # list current settings -git confg --global -l +git config --local -l # set line endings cd @@ -36,12 +36,12 @@ git config --local core.autocrlf "false" git config --local core.eol "lf" # list new settings -git confg --global -l +git config --local -l ``` ## Checking line endings -The quick and easy way to check the line endings used in a file you are working on is to look at the status bar at the bottom right of the VSC UI. `LF` indicates the file is using only `LF` characters. `CRLF` indicates that the ile is using `CR` + `LF` characters (which is a bad thing). To change the line endings used, simply click the `CRLF` text and change it to `LF` using the drop-down provided at the top of the UI. +The quick and easy way to check the line endings used in a file you are working on is to look at the status bar at the bottom right of the VSC UI. `LF` indicates the file is using only `LF` characters. `CRLF` indicates that the file is using `CR` + `LF` characters (which is a bad thing). To change the line endings used, click the `CRLF` text and change it to `LF` using the drop-down provided at the top of the UI. To change the line endings used, simply click the `CRLF` text and change it to `LF` using the drop-down provided at the top of the UI. ![Line end indicator](img/lf.png)