igodwin
f2a979f047
The repo is public and files are fetched by raw URL, so a reader who lands on one runbook never sees the README -- the repo's context does not travel with the file. Each .md now carries two lines under the title, each .ps1 the equivalent at the end of its .NOTES block. Deliberately two lines, not a paragraph. These files are read through `| more` on a client console mid-incident, and the top of the file is where the procedure-specific warnings live -- never a live chart, stop the service before copying, confirm authorization before acting. A legal preamble above those competes with them and trains people to skip past. Wording aims at a stranger who found the repo, not at the quality of the procedure: these double as documented-procedure evidence for E&O, and language implying the content is unreliable works against that. MIT rather than no license: the warranty and liability disclaimer is the part that does the work, and leaving it unlicensed makes reuse ambiguous rather than disclaimed. Also fixes 5 stale ops/rb URLs in scripts/*.ps1 that the previous commit missed -- it only swept the .md files. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HwcG1jLs1T425QRMxtjxP7
73 lines
2.8 KiB
Markdown
73 lines
2.8 KiB
Markdown
# Contributing (note-to-self)
|
|
|
|
Solo-maintained. This file exists to keep future-me honest.
|
|
|
|
## The rule
|
|
|
|
**Procedures only. No particulars.**
|
|
|
|
This repo is public-read. Anything that identifies a client or would let a
|
|
reader act against a client environment goes to the private tier — **no
|
|
exceptions.**
|
|
|
|
Never commit:
|
|
|
|
- Client / business names, site identifiers
|
|
- Hostnames, IPs, subnets, SSIDs, MAC addresses
|
|
- Usernames, account names, email addresses
|
|
- Passwords, keys, tokens, connection strings, license keys
|
|
- Screenshots, exports, logs, or config dumps containing any of the above
|
|
|
|
Instead use placeholders: `<CLIENT>`, `<SERVER>`, `<SHARE>`, `<SHARE_USER>`,
|
|
`<USER>`, `<PASSWORD>`. Filled-in versions live in the **private tier**
|
|
(private repo or Bitwarden secure note).
|
|
|
|
## Where things go
|
|
|
|
| Content | Home |
|
|
|---|---|
|
|
| Generic procedure with placeholders | **This repo** |
|
|
| Anything needing a credential | Private tier |
|
|
| Client-specific config / values | Private tier |
|
|
| Any identifying detail | Private tier |
|
|
|
|
If a step can't be written without a real particular, it doesn't belong here —
|
|
split the particular out to the private tier and reference it as a placeholder.
|
|
|
|
## Before every commit
|
|
|
|
1. Re-read the diff. Would a stranger learn *who* the client is, or *how to
|
|
reach* their systems? If yes, stop.
|
|
2. No real hostnames/IPs/users/passwords — placeholders only.
|
|
3. No screenshots or pasted output with real data.
|
|
4. Scripts prompt for client-specifics at run time; they don't hard-code them.
|
|
|
|
## Scripts
|
|
|
|
Scripts live under `scripts/`. Follow [`scripts/_template.ps1`](scripts/_template.ps1):
|
|
|
|
- Prompt for placeholders with `Read-Host` — no editing before running, no
|
|
`param()` (can't pass args through `irm | iex`).
|
|
- Safe to run via `irm <url> | iex` from our own server.
|
|
- Confirm before anything destructive or that reboots.
|
|
- Check for admin explicitly (`#Requires` is not enforced under `iex`).
|
|
|
|
## The as-is notice
|
|
|
|
Every runbook and script carries a short as-is notice — two lines under the `#`
|
|
title in a `.md`, or at the end of the `.NOTES` block in a `.ps1`. Copy it when
|
|
you add a file.
|
|
|
|
It is per-file rather than README-only for one reason: these are fetched by raw
|
|
URL, so a reader who lands on a single runbook never sees the README or the
|
|
LICENSE. The repo's context does not travel with the file.
|
|
|
|
Keep it to those two lines. It sits above genuinely important, procedure-specific
|
|
warnings — never a live chart, stop the service before copying, confirm
|
|
authorization before acting — and a longer legal preamble would train people to
|
|
skip the top of the file, which is exactly where those warnings live.
|
|
|
|
Aim it at a stranger who found the repo, not at the quality of the procedure.
|
|
These runbooks double as documented-procedure evidence; wording that implies the
|
|
content is unreliable works against that.
|