From 0326fd534e988ab2ec902bb0d4f20a8da05016a2 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Thu, 9 Jul 2026 03:13:46 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=96=20[Docs]:=20Remove=20Ways=20of=20W?= =?UTF-8?q?orking=20(now=20maintained=20in=20MSXOrg/docs)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Ways of Working section moved to the organization-wide docs site (MSXOrg/docs), which is now the authoritative, generalized, and expanded source. Removing the near-verbatim copies here avoids drift. Kept framework-specific content (PowerShell modules/scripts/DSC/function apps, Solutions) and the more detailed coding standards, which are not yet mirrored in MSXOrg. --- src/docs/PowerShell/Standard/index.md | 2 +- .../Infusing-GitHub-with-PowerShell.md | 4 +- .../Ways-of-Working/Commit-Conventions.md | 59 --- src/docs/Ways-of-Working/Git-Worktrees.md | 114 ----- src/docs/Ways-of-Working/Goal-Setting.md | 37 -- src/docs/Ways-of-Working/Issue-Format.md | 406 ------------------ src/docs/Ways-of-Working/Issue-Hierarchy.md | 118 ----- src/docs/Ways-of-Working/PR-Format.md | 181 -------- src/docs/Ways-of-Working/Principles.md | 309 ------------- .../Ways-of-Working/Readme-Driven-Context.md | 73 ---- src/docs/Ways-of-Working/Review-Etiquette.md | 100 ----- src/docs/Ways-of-Working/Workflow.md | 148 ------- .../continuous-x-and-continuous-ai.md | 156 ------- .../Ways-of-Working/development-practices.md | 85 ---- src/docs/Ways-of-Working/devops-reference.md | 160 ------- src/docs/Ways-of-Working/index.md | 22 - src/docs/index.md | 2 +- src/zensical.toml | 13 - 18 files changed, 4 insertions(+), 1985 deletions(-) delete mode 100644 src/docs/Ways-of-Working/Commit-Conventions.md delete mode 100644 src/docs/Ways-of-Working/Git-Worktrees.md delete mode 100644 src/docs/Ways-of-Working/Goal-Setting.md delete mode 100644 src/docs/Ways-of-Working/Issue-Format.md delete mode 100644 src/docs/Ways-of-Working/Issue-Hierarchy.md delete mode 100644 src/docs/Ways-of-Working/PR-Format.md delete mode 100644 src/docs/Ways-of-Working/Principles.md delete mode 100644 src/docs/Ways-of-Working/Readme-Driven-Context.md delete mode 100644 src/docs/Ways-of-Working/Review-Etiquette.md delete mode 100644 src/docs/Ways-of-Working/Workflow.md delete mode 100644 src/docs/Ways-of-Working/continuous-x-and-continuous-ai.md delete mode 100644 src/docs/Ways-of-Working/development-practices.md delete mode 100644 src/docs/Ways-of-Working/devops-reference.md delete mode 100644 src/docs/Ways-of-Working/index.md diff --git a/src/docs/PowerShell/Standard/index.md b/src/docs/PowerShell/Standard/index.md index 6bb8f24..a3a69f1 100644 --- a/src/docs/PowerShell/Standard/index.md +++ b/src/docs/PowerShell/Standard/index.md @@ -1,7 +1,7 @@ # PowerShell standards These standards apply to all PowerShell files across PSModule repositories. They implement the -engineering principles defined in [Principles](../../Ways-of-Working/Principles.md) — specifically +engineering principles defined in [Principles](https://msxorg.github.io/docs/Ways-of-Working/Principles/) — specifically *Clean Code*, *Make change easy*, *Shift Left*, and *Build for the modern engineer*. Each standard states the practice, why it matters to us, and how to apply it. diff --git a/src/docs/Solutions/Infusing-GitHub-with-PowerShell.md b/src/docs/Solutions/Infusing-GitHub-with-PowerShell.md index b63439e..70d9d7a 100644 --- a/src/docs/Solutions/Infusing-GitHub-with-PowerShell.md +++ b/src/docs/Solutions/Infusing-GitHub-with-PowerShell.md @@ -1,6 +1,6 @@ # Infusing GitHub with PowerShell -*Infuse GitHub with PowerShell* is the [mission](../Ways-of-Working/Goal-Setting.md) of the PSModule organization. GitHub gives mainstream languages — JavaScript, Python, .NET, Go — a rich, built-in developer experience: dependency updates, security scanning, package registries, setup actions, and a first-party API client. PowerShell is a first-class automation language, but on the GitHub platform it is treated as a second-class citizen. This initiative closes that gap. +*Infuse GitHub with PowerShell* is the [mission](https://msxorg.github.io/docs/Ways-of-Working/Goal-Setting/) of the PSModule organization. GitHub gives mainstream languages — JavaScript, Python, .NET, Go — a rich, built-in developer experience: dependency updates, security scanning, package registries, setup actions, and a first-party API client. PowerShell is a first-class automation language, but on the GitHub platform it is treated as a second-class citizen. This initiative closes that gap. We do it two ways: by **building** the PowerShell-native tooling the ecosystem is missing, and by **advocating** for the platform to support PowerShell where only the vendor can. This page describes the collection we have built and the capabilities we still want to make PowerShell-native. @@ -108,4 +108,4 @@ The gaps split into two kinds of work, matching how we operate: - **Build it.** Where a public API exists, we close the gap ourselves with a module or action: SARIF upload from PSScriptAnalyzer, dependency submission for module manifests, module caching for `Install-PowerShell`, and attestations on published modules. - **Advocate for it.** Where only the vendor can deliver — a native Dependabot ecosystem, a PowerShell Gallery entry in the Advisory Database, CodeQL support, OIDC trusted publishing, and a first-class package registry — we raise it with GitHub, Microsoft, and the Gallery, and ship a working interim in the meantime. -New parity gaps and concrete bets are tracked as [initiatives](../Ways-of-Working/Goal-Setting.md) under the mission. +New parity gaps and concrete bets are tracked as [initiatives](https://msxorg.github.io/docs/Ways-of-Working/Goal-Setting/) under the mission. diff --git a/src/docs/Ways-of-Working/Commit-Conventions.md b/src/docs/Ways-of-Working/Commit-Conventions.md deleted file mode 100644 index 485e452..0000000 --- a/src/docs/Ways-of-Working/Commit-Conventions.md +++ /dev/null @@ -1,59 +0,0 @@ -# Commit Conventions - -Commit messages serve two audiences: the engineer reading `git log` six months from now, and the agents trying to reconstruct what changed and why. Both need the same thing — **direct, descriptive messages** that say what was done. - -## Rules - -1. **State what was done or what the result is.** Imperative or declarative, both work. -2. **No conventional-commit prefixes.** No `fix:`, `feat:`, `docs:`, `chore:`, `refactor:`, etc. The change type is captured at the PR level — repeating it on every commit adds noise without information. -3. **No generic messages.** `Update for PR`, `WIP`, `fixes`, `more changes` — all forbidden. They erase traceability. -4. **One logical change per commit.** Micro-iterative discipline. If a change touches three unrelated concerns, that's three commits. -5. **Keep issue and pull request references out of commit messages.** Cross-references to issues and pull requests belong in the PR description and in issues — not in commit history. The pull request links the work to its issue (via a closing keyword such as `Fixes #123`); commits describe the change itself. - -## Examples - -### Good - -- `Add reserved word validation to Lua parser` -- `Correct hex float parsing for negative exponents` -- `Update installation prerequisites in README` -- `Remove deprecated Get-Widget cmdlet` -- `Switch pagination to link-header-based` -- `Add regression test for null context in Resolve-GitHubContext` - -### Bad - -- `fix: parsing bug` — prefix + vague. -- `Update for PR` — meaningless. -- `WIP` — never commit work that needs a placeholder message; squash or amend first. -- `Refactor stuff` — vague. -- `Changes` — ø. - -## Body (optional) - -A commit message body is fine for non-trivial changes that need context. Keep it short. Wrap at ~72 characters per line. - -```text -Switch pagination to link-header-based - -The previous page-number approach hardcoded the page size, which -breaks when the API returns the default. Link headers are what -the GitHub REST API documents as the supported pagination -mechanism. -``` - -## Why no conventional commits - -PSModule classifies changes at the PR level via labels and the change-type field. The release note is generated from the PR description, not from commit messages. Conventional-commit prefixes inside the repo: - -- Duplicate information already captured elsewhere. -- Encourage `chore:` and `refactor:` over descriptive messages. -- Lock the repo into a tooling pattern (Commitizen, semantic-release) that PSModule doesn't use. - -Direct, descriptive messages serve both engineers and agents without the ceremony. - -## When working with agents - -The Builder writes commits during the micro-iterative loop. Each commit covers one discrete change. The Responder writes commits when addressing review feedback — one commit per thread when practical, so the link between feedback and fix is preserved in history. - -Never let an agent commit with a placeholder message. If a commit can't be described in one clear line, the change is probably too broad — split it. diff --git a/src/docs/Ways-of-Working/Git-Worktrees.md b/src/docs/Ways-of-Working/Git-Worktrees.md deleted file mode 100644 index 40f98a5..0000000 --- a/src/docs/Ways-of-Working/Git-Worktrees.md +++ /dev/null @@ -1,114 +0,0 @@ -# Git Worktrees - -All repositories are set up as **bare clones with worktrees**. This enables parallel work — multiple agents (or a human and an agent) can work on different issues in the same repository simultaneously without conflicts, stashing, or context-switching. - -## Why worktrees - -| Problem with traditional clones | How worktrees solve it | -| -------------------------------------------- | --------------------------------------------------------- | -| Only one branch checked out at a time | Each issue gets its own worktree — parallel by default | -| Switching branches requires clean state | Worktrees are independent — no stashing or committing WIP | -| Agent work blocks human work on same repo | Different worktrees, no interference | -| Default branch gets dirty during development | `/` worktree is always a clean reference | - -## Repository layout - -```text -/ -├── .bare/ # bare git data (the actual repository) -├── .git # file containing: gitdir: ./.bare -├── / # worktree: default branch (always clean, never worked in directly) -├── 42-add-pagination/ # worktree: issue #42 in progress -└── 99-fix-null-ref/ # worktree: issue #99 in progress -``` - -- **`.bare/`** — the shared git object store. All worktrees share this. -- **`.git`** — a file (not a directory) that points git tooling to `.bare/`. -- **`/`** — the default branch worktree (e.g. `main` or `master`). Kept as a clean reference. Used for diffing, reading docs, running comparisons. Never directly committed to. -- **`-/`** — one worktree per issue in flight. Named by issue number and a short slug. Branch name matches the folder name. - -## Remotes - -Every repository has exactly two remotes (or one, if it is not a fork): - -| Remote | Points to | Required | Purpose | -| -------------- | ---------------------------- | -------- | ------------------------------------------------ | -| **`origin`** | Our copy on the server | Always | Push branches, open PRs, CI runs against this. | -| **`upstream`** | The parent repo (forks only) | Forks | Track upstream changes, sync the default branch. | - -No other remotes are added. This keeps the model simple and predictable for both humans and agents. - -### How it works in practice - -- **Non-fork repos** — only `origin` exists. Branches are pushed to `origin`, PRs are opened against `origin`. -- **Forked repos** — `origin` is our fork, `upstream` is the original repository. The default branch tracks `upstream` for syncing; feature branches are pushed to `origin` and PRs are opened from `origin` into `upstream`. - -### Fetch configuration - -Both remotes are configured with full refspecs so `git fetch --all --prune` keeps everything current: - -```text -[remote "origin"] - fetch = +refs/heads/*:refs/remotes/origin/* - -[remote "upstream"] # forks only - fetch = +refs/heads/*:refs/remotes/upstream/* -``` - -## Setup (one-time per repository) - -```powershell -# Clone as bare into .bare/ -git clone --bare https://github.com//.git .bare - -# Create the .git pointer file -Set-Content .git "gitdir: ./.bare" -NoNewline - -# Configure fetch refspec (bare clones don't set this automatically) -git -C .bare config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*' - -# Fetch remote branches -git -C .bare fetch origin - -# Determine the default branch -$defaultBranch = git -C .bare symbolic-ref HEAD | ForEach-Object { $_ -replace 'refs/heads/', '' } - -# Create the default branch worktree -git -C .bare worktree add "../$defaultBranch" $defaultBranch - -# Set upstream tracking (prevents "Publish Branch" prompt in VS Code) -git -C .bare config "branch.$defaultBranch.remote" origin -git -C .bare config "branch.$defaultBranch.merge" "refs/heads/$defaultBranch" -``` - -> The [Checkout-GitHubRepo](https://github.com/MariusStorhaug/.dev/blob/main/.github/Checkout-GitHubRepo.ps1) script automates this for all repositories. - -## Working on an issue - -```powershell -# From the repo root (where .bare/ lives) -$defaultBranch = git -C .bare symbolic-ref HEAD | ForEach-Object { $_ -replace 'refs/heads/', '' } -git -C .bare worktree add ../42-add-pagination -b 42-add-pagination $defaultBranch - -# Set upstream tracking (prevents "Publish Branch" prompt in VS Code) -git -C .bare config branch.42-add-pagination.remote origin -git -C .bare config branch.42-add-pagination.merge refs/heads/42-add-pagination - -# Open in VS Code -code 42-add-pagination -``` - -Then follow the normal Implement flow: initial commit → push → draft PR → build → finalize. - -## Cleanup after merge - -```powershell -# Remove the worktree -git -C .bare worktree remove 42-add-pagination - -# Delete the local branch ref -git -C .bare branch -D 42-add-pagination - -# Prune if needed (removes stale worktree references) -git -C .bare worktree prune -``` diff --git a/src/docs/Ways-of-Working/Goal-Setting.md b/src/docs/Ways-of-Working/Goal-Setting.md deleted file mode 100644 index 9ccdaff..0000000 --- a/src/docs/Ways-of-Working/Goal-Setting.md +++ /dev/null @@ -1,37 +0,0 @@ -# Goal-Setting Framework - -PSModule uses a lightweight OKR-based framework to connect strategic direction to day-to-day work. The hierarchy runs from the organisation's reason to exist down to individual deliverables tracked in GitHub issues. - -## Layers - -| Layer | Lives in | Purpose | -| --------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------- | -| **Mission** | [`PSModule/.github` #68](https://github.com/PSModule/.github/issues/68) | The org's reason to exist — *infuse GitHub with PowerShell* | -| **OKR** | Sub-issues of the Mission | Qualitative objectives + measurable key results | -| **Initiative** | Sub-issues of an OKR | A concrete bet to move a Key Result — becomes an Epic in a repo | - -## Why OKRs and not KPIs - -- **Objectives** are qualitative, aspirational, and outside-in. They describe a state of the world we want to see. -- **Key Results** are measurements that confirm the Objective is being met. They drive incentive in the right direction without prescribing the path. - -A good OKR is one that anyone — contributor, user, or agent — can read and immediately have ideas about how to contribute. See [Principles](Principles.md) for the full rationale. - -## Current OKRs - -Tracked as sub-issues of the [Mission issue](https://github.com/PSModule/.github/issues/68): - -- [Every module author ships with confidence](https://github.com/PSModule/.github/issues/69) -- [The framework handles complexity so authors don't have to](https://github.com/PSModule/.github/issues/70) -- [PSModule modules are the best-maintained on the Gallery](https://github.com/PSModule/.github/issues/71) - -## From strategy to delivery - -Initiatives are the bridge between strategy and execution. An Initiative is a sub-issue of an OKR and maps directly to an **Epic** in the relevant repository. From there it decomposes into PBIs and Tasks through the [Issue Hierarchy](Issue-Hierarchy.md). - -```text -Mission (org-level, evergreen) -└── OKR (qualitative objective + key results) - └── Initiative (concrete bet to move a KR) - └── Epic (in a repository) → PBIs → Tasks -``` diff --git a/src/docs/Ways-of-Working/Issue-Format.md b/src/docs/Ways-of-Working/Issue-Format.md deleted file mode 100644 index 3117291..0000000 --- a/src/docs/Ways-of-Working/Issue-Format.md +++ /dev/null @@ -1,406 +0,0 @@ -# Issue Format - -Every issue in the PSModule organization follows the same structure. The format makes issues: - -- **Readable** by anyone — human or agent — without prior context. -- **Actionable** by an implementer without back-and-forth. -- **Traceable** because decisions and changes are recorded. - -## Properties of every issue - -- **Every change has an issue.** Features, fixes, refactors, documentation, maintenance — all tracked as issues before work begins. -- **The description is the single source of truth.** It reflects the current state of the work at all times. Decisions, scope changes, and approach changes are written directly into the description. -- **Comments record change history only.** Each description update is accompanied by a comment summarizing what changed and why. -- **Tone is impersonal.** No first-person ("I", "my") or second-person ("you", "your") language. Neutral references like "the user", "the developer", or passive constructions. -- **External references are hyperlinks.** Every mention of an API, RFC, library, doc, or tool is a clickable `[text](url)` link. No bare URLs. -- **Issue and PR references are scoped to their target.** Use the `#123` shorthand for an issue or pull request in the same repository, and the fully qualified `Owner/Repo#123` form for one in another repository so the link resolves to the right place. Outside GitHub — Jira, Confluence, Slack, or any surface without GitHub autolinking — use the full URL (`https://github.com/Owner/Repo/issues/123`). -- **No duplicates.** Existing issues are searched before creating or restructuring. Duplicates are consolidated or cross-linked. - -## Title - -A clear, imperative-mood statement of the work. Not a question, not a symptom. - -- Scope or area when it aids disambiguation: `Build-PSModule: Add retry logic to publish step`. -- No type prefixes (`[Bug]`, `[Feature]`) — labels handle categorization. - -### Well-formed - -- `Add pagination support to Get-GitHubRepository` -- `Fix null reference when Context is not resolved` -- `Update installation guide with prerequisites` - -### Malformed - -- `Bug in module` -- `Please fix` -- `WIP` - -## The three sections - -The description has three sections separated by horizontal rules (`---`), ordered from behavioural to architectural to tactical. The user need is understood before the technical discussion. - -| Section | Owner | Present in | -| ------------------------- | --------------------- | ------------------------------------------------------------- | -| 1 — Context and Request | Ideator → Clarifier | Every issue at every level (Task, PBI, Epic) | -| 2 — Technical Decisions | Planner | Task always; PBI / Epic for decomposition rationale | -| 3 — Implementation Plan | Planner | Task always (task list); PBI / Epic (links to children) | - -## Section 1 — Context and Request - -Describes the **user experience** — what someone wants, what isn't working, or what is missing. Written from the user's perspective, not the implementer's. - -Two parts: - -- **Context** — who the user is, what they're trying to accomplish, the situation. -- **Request** — the problem or need, as the user experiences it. - -Answers: - -- What does the user want to do? -- What is the user experiencing today (for bugs / gaps)? -- What should the experience look like instead? -- Why does it matter? - -Framing by work type: - -| Type | Framing | -| -------------- | ------------------------------------------------------------------------------------ | -| Feature | **Desired capability:** The desired capability from the user's point of view. | -| Bug / Fix | **What happens:** / **What is expected:** Observed vs. expected behavior. | -| Change request | **Current experience:** / **Desired experience:** The shift from the user's lens. | -| Maintenance | **User impact:** How internal work improves reliability, speed, or correctness. | -| Documentation | **What is confusing or missing:** The gap from a user trying to accomplish a task. | - -Elements per work type: - -| Element | Feature | Bug / Fix | Change request | Maintenance | Documentation | -| ------------------------ | :-----: | :-------: | :------------: | :---------: | :-----------: | -| Acceptance criteria | ✓ | ✓ | ✓ | ✓ | ✓ | -| Reproduction steps | | ✓ | | | | -| Environment / version | | ✓ | | | | -| Regression indicator | | ✓ | | | | -| Known workarounds | | ✓ | ○ | | | -| Error messages / logs | | ✓ | | ○ | | -| Screenshots / visuals | ○ | ✓ | ○ | | ○ | - -✓ = present when applicable, ○ = optional - -Element definitions: - -- **Reproduction steps** — a [minimal reproducible example](https://en.wikipedia.org/wiki/Minimal_reproducible_example): exact steps, inputs, and commands that trigger the problem. Anyone can reproduce the failure without guessing. -- **Environment / version** — module version, PowerShell version (`$PSVersionTable`), and operating system. Other relevant runtime details (host application, execution context) included as applicable. Omitted only when clearly version-independent. -- **Regression indicator** — whether this previously worked, and in which version. If unknown, stated explicitly. -- **Known workarounds** — any mitigation available today, even if ugly or incomplete. - -This section contains: - -- Context: user story or scenario, background, what the user is trying to accomplish -- Request: the specific problem, gap, or desired change — as the user experiences it -- Current vs. desired experience -- Impact of not addressing this (data loss, confusion, blocked workflows) -- Acceptance criteria — what "done" looks like from the user's perspective -- Applicable work-type-specific elements from the table above -- Links to related issues, PRs, or external references — every external resource is a clickable hyperlink - -This section **does not contain** file paths, function internals, API endpoints, or implementation patterns. Those belong in Section 2. The section is understandable by someone who has never read the source code. - -**Example (Bug / Fix):** - -```markdown -`Get-GitHubRepository` is used in automation to sync all repositories for an account. -The script relies on getting the full list so it can detect new or removed repositories. - -## Request - -When `Get-GitHubRepository` is called on an account with more than 30 repositories, only 30 results are returned. -There is no indication that results are incomplete, so it appears as though the full list has been retrieved. -The silent truncation causes scripts to miss repositories, which can go unnoticed for weeks. - -### Reproduction steps - -1. Create or use an account with more than 30 repositories -2. Run `Get-GitHubRepository` -3. Count the returned objects — only 30 are returned regardless of total count - -### What is expected - -The command should return **all** repositories by default. If there is a way to limit results, -it should be opt-in — not the default. - -### Environment - -- **Module version:** 0.14.0 -- **PowerShell:** 7.4.6 (Linux, Ubuntu 22.04) - -### Regression - -This appears to have been the behavior since the initial release. Not a regression. - -### Workaround - -Calling the GitHub REST API directly with manual pagination returns all results. - -### Acceptance criteria - -- All repositories are returned by default, regardless of how many exist -- Results can be limited with a parameter when only a subset is needed -- No silent data loss — if something limits results, it should be explicit -``` - -**Example (Feature):** - -```markdown -Automation scripts that publish module releases to multiple registries currently call `Publish-PSResource` -in a loop for each target. There is no built-in way to publish to several registries in a single invocation. - -## Request - -### Desired capability - -A `-Repository` parameter on `Publish-Module` that accepts an array of registry names, publishing -the module to each in sequence. If any single publish fails, the error should be reported per-registry -without aborting the remaining targets. - -### Acceptance criteria - -- `-Repository` accepts one or more registry names -- Each target is attempted independently — a failure on one does not block the others -- Output clearly indicates success or failure per registry -``` - -## Section 2 — Technical Decisions - -The technical choices that shape the plan. Sits between the user-facing request and the tactical plan. - -Why this section exists: - -- Different technical choices lead to fundamentally different plans — deciding upfront avoids rework. -- Conscious, documented choices replace implicit assumptions buried in code. -- Reviewers see the **reasoning** behind the plan, not just the plan itself. - -Structure: - -- Each decision is a bolded label or heading, followed by the chosen approach and a brief rationale. -- Alternatives considered are included when they help explain the choice. -- Open decisions are marked with `Open:` and resolved before the implementation plan is written. -- When a decision changes later, this section is updated and a comment documents the change. - -Typical decision areas: - -- Where new code lives (paths, modules). -- Patterns or conventions followed (e.g., "follow the existing pattern in `Get-GitHubRelease`"). -- Naming choices. -- Whether to extend or create new. -- Dependencies on other functions, modules, or APIs. -- Error handling strategy. -- Breaking changes and backward compatibility. -- Test strategy (unit, integration, mocks). - -**Example:** - -```markdown ---- - -## Technical decisions - -**Function placement:** New private function goes in `src/functions/private/Utilities/` following the existing -`Invoke-GitHubRestMethod` pattern. Public function stays in `src/functions/public/Repository/`. - -**Pagination approach:** Use link-header-based pagination (`rel="next"`) rather than page-number incrementing. -The GitHub REST API uses link headers consistently, and this avoids hardcoding page size assumptions. - -**Parameter naming:** Use `-First` (consistent with PowerShell convention and `Select-Object -First`) rather than -`-Limit` or `-MaxResults`. - -**Breaking changes:** None. Default behavior changes from returning one page to returning all pages, but since the -previous behavior was undocumented and returning incomplete data, this is treated as a bugfix rather than a breaking change. - -**Test approach:** Unit tests with mocked API responses. One test per scenario: single-page, multi-page, and `-First` limiting. -``` - -## Section 3 — Implementation Plan - -The task-level roadmap. Implementers track progress here; reviewers use it to understand scope. - -Structure: - -- Every discrete piece of work is a checkbox: `- [ ]`. -- Tasks are grouped under subheadings when work spans multiple areas (files, components, tests). -- Each task is specific and actionable — file paths, function names, modules. -- All tasks start unchecked. Checking happens during implementation. -- Tasks are ordered logically — dependencies first, tests last. - -For PBIs and Epics, Section 3 is **a list of links to child issues**, not inline tasks. See [Issue Hierarchy](Issue-Hierarchy.md). - -**Example:** - -```markdown ---- - -## Implementation plan - -### Core changes - -- [ ] Add `Invoke-GitHubRestMethodPaged` private function in `src/functions/private/Utilities/` -- [ ] Update `Get-GitHubRepository` to call paged variant in `src/functions/public/Repository/` -- [ ] Add `-First` parameter with `[int]` type and validation - -### Tests - -- [ ] Add unit test for single-page response -- [ ] Add unit test for multi-page response -- [ ] Add unit test for `-First` parameter limiting results - -### Documentation - -- [ ] Update function help with new parameter documentation -- [ ] Add example showing pagination usage -``` - -## Comments - -Every description update is accompanied by a comment. Comments preserve the change history so reasoning is not lost when the description is overwritten. - -A comment contains: - -- A brief summary line. -- Bullet points detailing what was added, changed, or removed. -- Any gaps or open questions that need input. - -**Example:** - -```markdown -Structured the issue description into the standard three-section format. - -- Rewrote the context and request to separate user-facing behavior from technical details -- Added technical decisions section based on codebase research -- Created implementation plan with 6 tasks covering core changes, tests, and documentation -- Open question: should `-First` default to unlimited or require explicit opt-in? Marked as open in technical decisions. -``` - -## Formatting - -Issues use [GitHub Flavored Markdown](https://github.github.com/gfm/) with the full feature set: - -- `- [ ]` / `- [x]` task lists. -- Tables for comparisons, label definitions, decision matrices. -- Fenced code blocks with language identifiers. -- `>` blockquotes for callouts. -- `> [!NOTE]`, `> [!TIP]`, `> [!IMPORTANT]`, `> [!WARNING]`, `> [!CAUTION]` alerts. -- `
……
` collapsible sections. -- `#123`, `@user`, and commit SHA autolinks. -- Backtick-wrapped inline code for identifiers. -- `---` horizontal rules between sections. -- `[text](url)` links for all external references. -- **No hard line breaks within a paragraph.** GitHub renders mid-paragraph newlines as spaces, which creates inconsistent visual spacing. - -## Complete example - -A fully structured bugfix issue: - -**Title:** `Fix silent truncation of results in Get-GitHubRepository` - -**Labels:** `Patch`, `Bug` - -**Body:** - -```markdown -`Get-GitHubRepository` is used in automation to sync all repositories for an account. -The script relies on getting the full list so it can detect new or removed repositories. - -## Request - -When `Get-GitHubRepository` is called on an account with more than 30 repositories, only -30 results are returned. There is no indication that results are incomplete, so it appears -as though the full list has been retrieved. The silent truncation causes scripts to miss -repositories, which can go unnoticed for weeks. - -### Reproduction steps - -1. Create or use an account with more than 30 repositories -2. Run `Get-GitHubRepository` -3. Count the returned objects — only 30 are returned regardless of total count - -### What is expected - -The command should return **all** repositories by default. If there is a way to limit -results, it should be opt-in — not the default. - -### Environment - -- **Module version:** 0.14.0 -- **PowerShell:** 7.4.6 (Linux, Ubuntu 22.04) - -### Regression - -This appears to have been the behavior since the initial release. Not a regression. - -### Workaround - -Calling the GitHub REST API directly with manual pagination returns all results. - -### Acceptance criteria - -- All repositories are returned by default, regardless of how many exist -- Results can be limited with a parameter when only a subset is needed -- No silent data loss — if something limits results, it should be explicit - ---- - -## Technical decisions - -**Function placement:** New private function goes in `src/functions/private/Utilities/` following -the existing `Invoke-GitHubRestMethod` pattern. Public function stays in -`src/functions/public/Repository/`. - -**Pagination approach:** Use link-header-based pagination (`rel="next"`) rather than page-number -incrementing. The GitHub REST API uses link headers consistently, and this avoids hardcoding page -size assumptions. - -**Parameter naming:** Use `-First` (consistent with PowerShell convention and `Select-Object -First`) -rather than `-Limit` or `-MaxResults`. - -**Breaking changes:** None. Default behavior changes from returning one page to returning all pages, -but since the previous behavior was undocumented and returning incomplete data, this is treated as a -bug fix rather than a breaking change. - -**Test approach:** Unit tests with mocked API responses. One test per scenario: single-page, -multi-page, and `-First` limiting. - ---- - -## Implementation plan - -### Core changes - -- [ ] Add `Invoke-GitHubRestMethodPaged` private function in `src/functions/private/Utilities/` -- [ ] Update `Get-GitHubRepository` to call paged variant in `src/functions/public/Repository/` -- [ ] Add `-First` parameter with `[int]` type and validation - -### Tests - -- [ ] Add unit test for single-page response -- [ ] Add unit test for multi-page response -- [ ] Add unit test for `-First` parameter limiting results - -### Documentation - -- [ ] Update function help with new parameter documentation -- [ ] Add example showing pagination usage -``` - -## Labels - -Labels categorize. The category is never encoded in the title. - -| Label | Use for | -| ----------- | ---------------------------------------------------- | -| `Major` | Breaking changes | -| `Minor` | New features or enhancements | -| `Patch` | Small fixes or improvements | -| `NoRelease` | Documentation, maintenance, CI/CD — no version bump | -| `Bug` | Bug reports | -| `Feature` | Feature requests | -| `Question` | Questions or discussion | - -Issue **types** (Epic / PBI / Task) are GitHub-native and separate from labels — see [Issue Hierarchy](Issue-Hierarchy.md). diff --git a/src/docs/Ways-of-Working/Issue-Hierarchy.md b/src/docs/Ways-of-Working/Issue-Hierarchy.md deleted file mode 100644 index 09a88f8..0000000 --- a/src/docs/Ways-of-Working/Issue-Hierarchy.md +++ /dev/null @@ -1,118 +0,0 @@ -# Issue Hierarchy - -Work in PSModule is tracked using GitHub sub-issues to form a connected hierarchy from Epic down to individual deliverables. The level reflects **scope and aggregation**, not priority or complexity. We use **GitHub issue types** for the segmentation — not labels — so the relationships are first-class in the platform. - -Epics originate from Initiatives in the [Goal-Setting Framework](Goal-Setting.md). - -## Full hierarchy - -```text -Epic (initiative from an OKR, repo-level) -├── PBI (body of work, multiple PRs) -│ ├── Task (one PR-sized deliverable) -│ └── Task -└── PBI - └── Task -``` - -GitHub supports up to **8 levels** of nested sub-issues and **100 sub-issues per parent**, which comfortably fits this model with room to spare. - -## The three operational levels - -| Level | Issue type | Scope | Output | -| ------------------------ | ------------ | -------------------------------------------------- | ---------------------------------------------------------- | -| **Task** | `Task` | One deliverable. One small reviewable PR. | Working software. | -| **Product Backlog Item** | `PBI` | A body of work composed of multiple Tasks. | Tracking, delegation, oversight, visibility into progress. | -| **Epic** | `Epic` | Strategic chunk needing multiple PBIs. | The co-planning artifact. Where OKRs become initiatives. | - -> The name **Product Backlog Item** is chosen for its neutral vibe — it works equally well for a feature, a fix, a refactor, or an internal capability. "Feature" implies user-visible value, which isn't always the case for the middle tier. - -## When to use each level - -### Task - -Use Task when: - -- The work has one clear deliverable. -- The expected PR is small and reviewable in a single pass (rough guideline: under ~500 lines / 15 files). -- One person (or one agent) can pick it up and finish it independently. - -A Task is the **default starting point**. Promote upward only when you discover the work is too big. - -### Product Backlog Item - -Use PBI when: - -- The work has multiple distinct deliverables, each of which would be its own PR. -- The deliverables share a goal but can be sequenced or parallelized. -- You want oversight over the body of work without prescribing the order. - -A PBI's children can themselves be PBIs (nested decomposition) when the inner deliverables also break into multiple chunks. Epic → PBI → PBI → Task is legitimate when the work demands it. - -### Epic - -Use Epic when: - -- The work spans multiple PBIs. -- It maps to a strategic objective — an OKR, an initiative, an organizational goal. -- Multiple teams or contributors should co-plan around it. - -> "As a business we want to deliver this. What do we collectively need to do?" - -That conversation lives on an Epic. - -## Nested decomposition - -Nesting is fine and expected: - -```text -Epic (initiative, ties to an OKR) -├── PBI (one body of work) -│ ├── Task (one PR) -│ ├── Task -│ └── PBI (further breakdown when needed) -│ ├── Task -│ └── Task -└── PBI - └── Task -``` - -The rule: **one Task = one PR-sized deliverable**. Everything above is for aggregation. - -## How to express the hierarchy - -Use GitHub's **sub-issue relationship** between issue types. This is a first-class GitHub feature — not just text references — and the [Planner](https://github.com/PSModule/.github-private/blob/main/agents/planner.md) agent creates these relationships when decomposing. - -Text-level conventions on child issues: - -- `Parent: #N` at the top of Section 1 (a courtesy duplicate of the GitHub link). -- `Blocked by: #M` when sequencing matters. -- Acceptance criteria scoped to **just this child's slice**, not the parent's whole goal. - -## How the sections differ by level - -| Section | Task | PBI | Epic | -| ------------------------ | ----------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------- | -| Section 1 (Context/Req) | The deliverable's user story | The grouped goal's user story | The strategic outcome — vision, why, the change in the world | -| Section 2 (Decisions) | Implementation decisions | Decomposition rationale + interface decisions between children | Decomposition rationale + which PBIs and why | -| Section 3 (Plan) | Checkbox task list | Linked list of child issues (Tasks and/or sub-PBIs) | Linked list of child PBIs | - -For Epics, Section 1 should explicitly contain the **Golden Circle framing**: Why, How, What. See [Principles → Golden Circle](Principles.md#start-with-why--the-golden-circle). - -## Why three levels and not more - -Three is enough to: - -- Cover **strategic** (Epic), **tactical** (PBI), and **operational** (Task) horizons. -- Match how teams co-plan in larger frameworks (SAFe, Nexus) without inheriting their ceremony. -- Aggregate progress meaningfully — an Epic burns down as its PBIs complete; a PBI burns down as its Tasks complete. - -More levels create overhead. Fewer levels lose the ability to track progress across bodies of work. - -## Promotion and demotion - -A Task can be **promoted** to a PBI when it turns out to be bigger than expected. The Planner does this — Section 2 records the discovery, and the inline task list becomes child issues. - -A PBI can be **demoted** to a Task when decomposition reveals only one real deliverable. Close the would-be-children, fold their content into the Task's Section 3. - -Promotion / demotion always leaves a comment audit trail explaining the change. diff --git a/src/docs/Ways-of-Working/PR-Format.md b/src/docs/Ways-of-Working/PR-Format.md deleted file mode 100644 index 2d03d08..0000000 --- a/src/docs/Ways-of-Working/PR-Format.md +++ /dev/null @@ -1,181 +0,0 @@ -# PR Format - -Pull requests in PSModule double as **release notes**. The description is written for end users of the solution, not for reviewers or developers. Implementation details go in a clearly separated technical section at the bottom. - -## Title - -```text - []: -``` - -- The **Icon** matches the change type. -- The **Type** in brackets is one of: `Major`, `Feature` (Minor), `Patch`, `Fix`, `Docs`, `Maintenance`. -- The **outcome** describes what changed from the end user's perspective. Never internal function names, class names, refactoring verbs. - -### Good titles - -- `🌟 [Major]: Get-Widget cmdlet removed` -- `🚀 [Feature]: Custom module templates now supported` -- `🩹 [Patch]: Default timeout value corrected` -- `🪲 [Fix]: Parameter validation no longer fails on null input` -- `📖 [Docs]: Installation guide updated with prerequisites` -- `⚙️ [Maintenance]: Release workflow and dependencies updated` - -### Bad titles - -- `Add support for custom module templates` — describes the action, not the outcome. -- `Refactor parameter validation logic` — implementation language. -- `Update stuff` — meaningless. - -## Change types - -| Type | Icon | Label | Description | -| ----------- | ---- | ----------- | ----------------------------------------------------- | -| Major | 🌟 | `Major` | Breaking changes that affect compatibility | -| Minor | 🚀 | `Minor` | New features or enhancements | -| Patch | 🩹 | `Patch` | Small fixes or improvements | -| Fix | 🪲 | `Patch` | Bugfixes (Patch-level release impact) | -| Docs | 📖 | `NoRelease` | Documentation changes only | -| Maintenance | ⚙️ | `NoRelease` | CI/CD, build configs, AI/agent files, internal upkeep | - -### Detecting the change type - -The change type is decided in this order: - -1. **Explicit user input** — if the contributor / Shipper specified a type, use it. -2. **Pre-1.0.0 rule** — projects with no version tags or latest tag below `v1.0.0` follow [SemVer §4](https://semver.org/#spec-item-4). Major is **never** auto-detected for pre-1.0.0 projects. Breaking changes there are classified as Minor (`0.x.0`). -3. **Artifact-based inference** from the branch diff: - - | Artifact type | How to recognize | Important files (affect artifact) | Non-important (framework / tooling) | - | ---------------------- | ------------------------------------------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------- | - | PowerShell Module | `src/` with `.ps1`/`.psm1`, or a `.psd1` manifest | `src/**`, `*.psd1`, `*.psm1` | `.github/**`, `*.md`, `tests/**`, `scripts/**`, `agents/**` | - | GitHub Action | `action.yml` at repo root | `action.yml`, `src/**` | `.github/**`, `*.md`, `tests/**`, `agents/**` | - | Reusable Workflow | `.github/workflows/` with callable workflows | `.github/workflows/**` | `*.md`, `tests/**`, `agents/**` | - -4. **Classification rules** (apply in order): - 1. **Docs** — all changes are documentation only. - 2. **Maintenance** — all changes are non-important for the artifact (no shipped change). - 3. **Patch** — important-file changes are small fixes or minor improvements. - 4. **Minor** — important-file changes add features without breaking. - 5. **Major** — important-file changes break backward compatibility (pre-1.0.0 → downgrade to Minor). - -If the branch contains both important and non-important changes, classify based on the important changes only. - -## Description structure - -Ordered, top to bottom. - -### 1. Leading paragraph — Summary - -A concise paragraph describing **what changes for the user**. Present tense, active voice. Never open with implementation language ("Refactored", "Updated class", "Added null checks"). - -### 2. User-facing changes — sections with headers - -Organize by **what the user experiences**, not by what was changed internally. - -- `## Breaking Changes` — what stopped working or changed incompatibly (Major only). -- `## New: ` — new things the user can do. -- `## Changed: ` — existing behavior that now works differently. -- `## Fixed: ` — problems now resolved. - -Under each header: - -- What the user can now do, or what changed for them. -- What they need to do differently — migration steps, new parameters, changed defaults. -- Examples or code snippets showing new usage. - -Do **not** mention internal function names, class names, private APIs, or refactoring decisions here. - -### 3. Technical details (optional) - -```markdown -## Technical Details -``` - -For reviewers and maintainers. Not part of the release note. Include: - -- Which internal functions, classes, or files were changed. -- Implementation approach and design decisions. -- Backward compatibility notes for developers. -- **Implementation plan progress** — cross-reference Section 3 of the linked issue. Which tasks does this PR complete? Which remain? - -Omit the section entirely if there's nothing noteworthy. - -### 4. Related issues - -A collapsible `
` block at the very end of the description containing issue links. Use the `#123` shorthand for issues in the same repository and the fully qualified `Owner/Repo#123` form for issues in another repository so links resolve to the right place. When a reference appears outside GitHub (release announcements, Jira, Slack, external docs), use the full URL (`https://github.com/Owner/Repo/issues/123`). - -```markdown -
-Related issues - -- Fixes #123 -- PSModule/Process-PSModule#124 - -
-``` - -One bullet per linked issue. Use a [closing keyword](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue) (`Fixes`, `Closes`, `Resolves`) when the PR fully addresses the issue. Otherwise, list the reference without a keyword to indicate a relationship without auto-closing. - -If no issue is linked: **stop**. PRs without issues break the workflow. Route back to the [Ideator](https://github.com/PSModule/.github-private/blob/main/agents/ideator.md) or proceed only on explicit user confirmation. The Shipper enforces this. - -## Formatting - -- Paragraphs are written as a **single unbroken line**. GitHub renders mid-paragraph newlines as spaces. -- The PR description is **the release note**. Write it for users, not reviewers. -- If a linked issue exists, the PR title and description should align with the issue's user-facing framing and the Technical Decisions section (Section 2). - -## Example - -````markdown -Repository objects now include custom properties directly — no separate API call needed. Queries that encounter missing or inaccessible resources now return partial results with warnings instead of failing entirely. - -## New: Custom properties on repository objects - -`Get-GitHubRepository` now returns custom properties inline on the repository object. Previously, retrieving custom properties required a separate call to `Get-GitHubRepositoryCustomProperty`. - -```powershell -$repo = Get-GitHubRepository -Owner 'MyOrg' -Name 'MyRepo' -$repo.CustomProperties | Format-Table -``` - -`Get-GitHubRepositoryCustomProperty` remains available if only the properties are needed. - -## Fixed: Queries no longer fail when a resource doesn't exist - -Commands that query a specific repository, enterprise, or release by name now return nothing instead of throwing when the resource doesn't exist. This makes them safe to use in conditional logic without try/catch. - -## Technical Details - -- `GitHubRepository` class: `CustomProperties` property changed from `[PSCustomObject]` to `[GitHubCustomProperty[]]`. -- `Invoke-GitHubGraphQLQuery`: error handling split into partial-success (data + errors → warnings) and full-failure (errors only → terminating error) branches. -- Null guards added to `Get-GitHubRepositoryByName`, `Get-GitHubMyRepositoryByName`, and related functions. -- Implementation plan progress: tasks 1–3 in #218 completed; task 4 (integration tests) remains. - -
-Related issues - -- Fixes #218 -- #219 - -
-```` - -## Drafts and readiness - -- The Shipper always creates the PR as **draft** so CI attaches immediately. -- Marking ready for review is the contributor's decision — never the agent's. -- Suggested gates before marking ready: tests pass locally, description finalized, no known issues. - -## Branches and commits - -- Branch naming: `/-`, e.g. `fix/123-pagination-truncation`. -- Commit messages: plain, direct, descriptive. **No conventional-commit prefixes** (`fix:`, `feat:`, `docs:`). See [Commit Conventions](Commit-Conventions.md). -- Self-review the staged diff before each commit. Unintended files (debug output, editor temp, credentials) get caught before they reach the remote. - -## Labels and assignment - -- Apply the change-type label. -- Apply phase labels if the repo uses them (Planning, Implementation, etc.). -- Assign the current user. -- Request reviewers per `CODEOWNERS`; if none, fall back to repo defaults or skip. diff --git a/src/docs/Ways-of-Working/Principles.md b/src/docs/Ways-of-Working/Principles.md deleted file mode 100644 index 6038d0c..0000000 --- a/src/docs/Ways-of-Working/Principles.md +++ /dev/null @@ -1,309 +0,0 @@ -# Principles - -The ideas underneath how we work — with each other and with our agents. These are evergreen. The agent definitions and the rest of the Agents docs reference them. - -## Purpose and direction - -### Start with Why - -Every piece of work — at every level — should be groundable in three concentric questions: - -- **Why** — what change in the world are we trying to make? Vision. -- **How** — what approach do we take to make that change happen? Mission. -- **What** — what concrete thing are we delivering right now? OKRs → initiatives → tasks. - -When an issue is being written, the **Why** belongs in the Context part of Section 1. The **How** belongs in Section 2 (Technical Decisions). The **What** belongs in Section 3 (Implementation Plan). - -### Product / service mindset - -We are building something for people who should **want** to use it. Without users, we are nothing. Every decision is filtered through: does this make the product more wanted, or less? - -### Build for all developers - -We target all platforms and all shells. Our code, scripts, workflows, and documentation must work regardless of whether the developer is on Windows, macOS, or Linux. Line endings, path separators, shell assumptions — none of these should silently break someone's experience. Repository configuration (`.gitattributes`, CI matrices, test environments) must reflect this. - -### Build for the modern engineer - -We build for engineers using the latest tools and platforms. We do not support deprecated or end-of-life software. Concretely: we target **PowerShell** (cross-platform, actively developed) — not Windows PowerShell (legacy, frozen at 5.1). The same applies across the stack: latest stable releases, current LTS versions, modern APIs. If a tool has a successor, use the successor. - -### Dogfooding - -Be the first customer of every service we build. But avoid full self-dependency on a service before it is proven — explore and use it in non-critical contexts first, then promote it as confidence grows. - -### Least-privilege - -Every identity — human, agent, or workflow — gets only the permissions it needs to complete its specific task, and nothing more. This applies to GitHub tokens, workflow permissions, API scopes, and agent capabilities. - -Concretely: - -- Workflow jobs declare `permissions` explicitly and as narrowly as possible. A job that only reads should never have write access. -- Agents are scoped to the actions they are authorised to take. An agent that reviews code should not be able to merge. -- Secrets and tokens are never passed wider than the step or job that needs them. -- When a required scope expands, that expansion is a deliberate, reviewed decision — not a default or a shortcut. - -The goal is to limit blast radius. If an agent, token, or job is compromised or behaves unexpectedly, least-privilege ensures the damage is contained. - -## AI-first development - -We practice AI-first development. AI agents are part of how we think, build, and deliver — not an afterthought bolted on at the end. Every workflow, every process, and every piece of documentation is designed with agents as first-class participants. - -That said, engineering is not fully non-deterministic. Our priority order is clear: **build deterministic software first, invoke AI where determinism falls short.** A script that always produces the correct answer is better than a prompt that usually does. AI fills the gaps that deterministic logic cannot cover — ambiguity, judgment, creativity, natural language, and tasks where the search space is too large for hand-written rules. - -The result: AI is always available, always integrated, always ready — but it earns its place by handling what deterministic tools cannot. - -### Determinism before intelligence - -LLM tokens are not the right tool for work that has a deterministic answer. Use agents to **build** the deterministic tool — a script, a library, a converter — and then run the tool. Don't burn tokens on work a function call can do. - -Practices: - -- If a problem has a closed-form solution, write code — not a prompt. -- Use AI to generate the deterministic tool, then discard the AI from the runtime path. -- Reserve AI for tasks that genuinely require reasoning, judgment, or natural language understanding. -- Audit existing AI-powered workflows: can any step be replaced by a deterministic function? -- AI is excellent for ad-hoc alignment work — "do X across all repos" — but the end goal is always to codify the result into repeatable, deterministic automation. - -### Human–agent coexistence - -The workflow is designed for humans and agents working side by side. Agents join a good human way of working — they do not replace it or require a parallel system. The operating model is **human-first, agent-augmented**. - -Agents are trained to read documentation. That is their natural skill. By keeping standards, conventions, and principles in documentation format we serve both audiences with a single artifact — no separate "agent manual" required. - -Agent context is delivered through three layers, in priority order: - -1. **Documentation** — the primary source. Published docs at , READMEs, and issue bodies are written for humans and naturally consumable by agents. -2. **Central agent configuration** — organization-wide agent files in `.github-private`. Thin orchestrators built mostly from references to the docs. They define roles, boundaries, and procedural steps — not standards or conventions. -3. **Local repository files** — `.github/` instruction files and repo-level overrides for what is unique to a single repository. - -### Augmentation, not replacement - -Agents amplify the team. They make us faster, more consistent, and free us from work that is mechanical. **Human in the loop** remains the default for decisions that matter. - -### Persona, not swarm - -Treat the agent ecosystem as one team mate. Many specialized roles, one cohesive bank of knowledge, one consistent voice. - -### Self-improving agents - -Agents need feedback and a way to process it. Every agent definition should evolve as we learn. Capture lessons in the agent definitions and in this docs section — don't let them live only in someone's head. - -### Integration and sensoring - -- **Integration** — the agent's ability to act on a platform as if it were human. GitHub, the editor, the terminal. -- **Sensoring** — the agent's ability to notice that it is needed. Webhooks, scheduled checks, signals from the platform. - -### Context-first development - -Every change flows through context before it touches code: - -```text -Intention of change → Update documentation → Update README → Update tests → Update code -``` - -Code echoes the docs, not the other way around. The README and the docs are the **specification**. Tests validate the interface we want to see. If a change isn't reflected in context first, the code has no contract to implement against — and agents have nothing to read. - -This means: - -- A new feature starts as a documented intent (issue, README update, or docs change) before any code is written. -- Tests are written or updated to assert the interface the documentation describes — before the implementation exists. -- A refactor updates the relevant documentation **first**, then the tests, then the code follows to match. -- If the docs and the code disagree, the docs are wrong — fix the docs, fix the tests, then fix the code to match. - -This is what makes agentic development work at scale. Agents read context. If the context is stale or missing, the agent builds the wrong thing. Keeping context ahead of code is how we stay in control. - -See [README-Driven Context](Readme-Driven-Context.md). - -### Context as a product - -The work of keeping context **right, evergreen, and declarative** runs alongside software delivery: - -- **Software delivery** produces code, tests, and releases using source control, CI/CD, and DevOps practices. -- **Context maintenance** produces issues, decisions, READMEs, agent definitions, and documentation — and treats them as products that must be kept current. - -Both run continuously. Each iteration of software delivery produces context that needs maintenance; each iteration of context maintenance unblocks the next round of software work. - -See [Workflow](Workflow.md) for how these connect in practice. - -### 4-eyes (or N-eyes) principle - -Every change benefits from a second perspective. With AI in the loop, that can be: - -- A human reviewing your work. -- You bouncing ideas off an agent. -- Multiple agents reviewing each other's output against the same standards. - -The goal is the same: catch what one perspective misses. - -### Code review as shared practice - -Pull request reviews are not just a quality gate — they are a cultural practice. Reviewing serves multiple purposes beyond catching defects: - -- **Learning and awareness.** Reviews spread knowledge across the team. A reviewer learns how a new area works; an author learns alternative approaches. Over time, the entire team develops a broader understanding of the codebase. -- **Shared responsibility.** Both author and reviewer share ownership of the changes that land. The author is responsible for proposing a sound change; the reviewer is responsible for validating it meets the team's standards. Once merged, the change belongs to both — neither can disclaim it. - -This means reviews are not adversarial. They are collaborative. A reviewer who approves a change is co-signing it. An author who receives feedback is gaining a perspective they didn't have alone. Treat both roles with the seriousness they deserve. - -## Software design - -### SOLID — in plain language - -- **Single Responsibility.** One thing does one thing. -- **Open / Closed.** Extend by adding, not by modifying what already works. -- **Liskov Substitution.** If something derives from a base, it should be safely usable wherever the base is expected. -- **Interface Segregation.** Don't make consumers depend on things they don't use. -- **Dependency Inversion.** Depend on abstractions, not concretions. - -### DRY — with judgment - -Don't Repeat Yourself, but **don't extract too early**. Wait until the same non-trivial logic appears in three or more places, or until the duplication is clearly load-bearing. Premature abstraction is more expensive than duplication. - -### Clean Code - -Write code that is understandable. Code is read more often than it is written. Names, structure, and intent come before cleverness. - -> Code should read like prose. It should tell a story that is easy to follow. - -### Evolutionary design / architecture - -Don't decide what you don't yet know. Experiment, iterate, treat design as a product — not a fixed contract. Architecture earns its right to be permanent by surviving change. - -### Make change easy, then make the easy change - -When a change is hard, resist the temptation to force it. First, restructure the system so the change becomes easy — as a separate, focused step. Then make the change itself. This separates two concerns: - -- **Prepare** — refactor, rename, extract, reorganise. No behaviour change. -- **Change** — add, remove, or alter behaviour. No structural churn. - -Applied recursively: if the preparation step is also hard, first make that easy. Work like a zipper — each structural step unlocks the next, until the actual behaviour change is trivial. - -Keeping the two steps separate also lets you apply different levels of rigour. Structural changes are reversible — an extracted helper can be inlined again, a rename can be undone. Behaviour changes are often not — output sent, a form filed, a side effect triggered cannot be recalled. Irreversible decisions deserve more care. Separating the two gives you room to apply that care where it actually matters. - -## Engineering practices - -### Write it down - -If something is only in your head: - -- Nobody else can work with you on it. -- You cannot reflect on it. -- It can escape you and be lost. - -**Write it down.** Issues, decisions, plans, READMEs. Writing is how knowledge becomes shared and how agents can help. - -### Everything as Code - -Everything — workflows, configuration, infrastructure, processes, agent definitions, even the docs you are reading — lives in source control. This is the bedrock of human-agent interaction. An agent can read code, change code, propose code. It cannot read what's only in someone's memory. - -### Documentation lives close to the thing it documents - -- Comment-based help lives next to the function. -- README lives at the root of the repo. -- Workflow guidance lives in the org-level docs (this site). -- Decisions live in the issue that produced them. - -Distance between a thing and its documentation is the rate at which they drift apart. - -### Test-Driven Development - -Define the tests when you define the behavior. Update them when behavior changes. Tests are the executable specification. - -### Shift Left - -Move quality gates as early as possible in the development cycle. The later a problem is caught, the more expensive it is to fix — a failing test in the editor is free; a bug in production is not. Design solutions so that validation happens at the earliest possible moment, not as an afterthought. - -#### Testable locally - -A developer (or agent) must be able to run the full test suite locally, without requiring cloud resources, special access, or environment secrets that can't be mocked. If you can't test it on your machine, you can't reason about it in your editor. - -This is a design constraint, not an optional addition. A solution that is untestable locally has a hidden cost that compounds with every change. When building new workflows, modules, or automation, ask early: *can someone run this locally?* - -#### Pre-commit hooks - -Validation that runs automatically on `git commit` — before the change enters history and before a PR is opened. Pre-commit hooks close the gap between "I can test it locally if I choose to" and "it is always checked before it leaves my machine." - -Typical gates: linting, formatting, static analysis, secret scanning, and fast unit tests. Keep them fast enough to not interrupt flow — if a hook takes more than a few seconds, it will be bypassed. - -#### Validatable in PRs - -Every pull request must trigger automated checks that verify correctness before a human review begins. Tests, linting, module analysis, or any other relevant gate must run in CI on each PR. - -A solution without PR validation shifts the cost of catching regressions onto reviewers — and reviewers miss things. Automation catches what humans don't, consistently and at no extra cost per PR. - -### Local testing for quick iterations - -Make it easy to build, test, and run locally. The inner loop is where most engineering time is spent — every second saved there compounds. - -Inner / outer loops to be aware of: - -- **Innermost** — write code, save, see result. Sub-second. -- **Inner** — run tests, see result. Seconds to a minute. -- **Outer** — push, CI, review, merge. Minutes to hours. -- **Outermost** — release, deploy, user feedback. Days to weeks. - -Push work as far inward as it can go. - -### 1-2-Automate - -If you've done a thing twice, the third time it should be automated. Sometimes you already know — go straight to automation. Extreme automation is often the right starting point. - -### DevOps and SRE - -> You build it, you run it. - -Everything is continuous — development, integration, delivery, operation. The same team owns the system across the loop. Build the systems, the practices, and the teams that internalize this. - -## Planning and delivery - -### Roadmapping - -We plan in a 3×3 matrix: - -| | Now | Next | Later | -| ------------ | ------------ | -------------- | -------------- | -| Conceptual | Vision today | Vision next | Vision later | -| Logical | Approach now | Approach next | Approach later | -| Detailed | Tasks now | Tasks next | Tasks later | - -- **Now / Next / Later** are time horizons without firm dates. -- **Conceptual / Logical / Detailed** are levels of fidelity. - -The detail increases as work moves from Later toward Now. - -### Lean Software Development - -Start very thin. Get the team's ideas flowing. Enable more people to contribute. Don't build for tomorrow's requirements (**YAGNI**). - -The iteration phases — and we move through them quickly, sometimes in parallel: - -1. **Spike / Experiment** — can this thing even be built? -2. **Proof of Concept** — does the experiment survive contact with reality? -3. **MVP** — first version we can run in production. Start collecting real feedback. -4. **Improvements** — stabilize, add functionality, harden. - -The best feedback is the feedback from people who have seen the thing. - -### Ways of working - -One size does not fit all. The way we work follows the principles above, including the principle of evolving how we work. - -- **Start lean** with processes and ceremonies. Get to know each other and the work first. -- **Scrum + Kanban hybrid** — dynamic cycles, no firm sprint end dates. A cycle is over when an Epic is delivered. Estimation is approximate; Epics themselves are kept lean. -- **Limit Work in Progress.** Roughly three concurrent items per person is the typical ceiling for sustained focus. -- **Extreme Programming** — pair programming (human + human, or human + agent) as a vehicle for learning, decision-making, review, and validation. - -## Why these principles matter - -These are the assumptions every agent decision rests on. When an agent's behaviour is unclear or contested, the answer comes from here. When something here turns out to be wrong, update this page — not just one agent. - -## References - -Literature and books that inform these principles: - -- **Start With Why** — Simon Sinek. The Golden Circle framework (Why → How → What) that grounds our purpose-first approach. [simonsinek.com](https://simonsinek.com/books/start-with-why/) -- **Measure What Matters** — John Doerr. The OKR framework we use for goal-setting — objectives over KPIs. [whatmatters.com](https://www.whatmatters.com/) -- **Getting Things Done** — David Allen. The discipline of writing things down so they can be shared, reflected on, and acted upon. [gettingthingsdone.com](https://gettingthingsdone.com/) -- **Clean Code** — Robert C. Martin. Readability, naming, and structure over cleverness. -- **Refactoring** — Martin Fowler. Make change easy, then make the easy change. -- **The Pragmatic Programmer** — David Thomas and Andrew Hunt. Evolutionary design, DRY, and automation as default. -- **Accelerate** — Nicole Forsgren, Jez Humble, Gene Kim. The research behind DevOps, Shift Left, and continuous delivery. -- **Lean Software Development** — Mary and Tom Poppendieck. Start thin, eliminate waste, deliver fast. diff --git a/src/docs/Ways-of-Working/Readme-Driven-Context.md b/src/docs/Ways-of-Working/Readme-Driven-Context.md deleted file mode 100644 index 9ec3b96..0000000 --- a/src/docs/Ways-of-Working/Readme-Driven-Context.md +++ /dev/null @@ -1,73 +0,0 @@ -# README-Driven Context - -The README is the **evergreen context document** for every repository in the PSModule organization. It is the single source of truth for what a repository is, what it does, and how it works. Both humans and agents read the README before starting work — and update it whenever functionality changes. - -## Core principles - -- **The README is the front door.** Anyone — human or agent — encountering the repository for the first time should understand the purpose, scope, and current capabilities from the README without reading source code. -- **The README is evergreen.** It is a living document that always reflects the current state of the repository. When functionality is added, changed, or removed, the README is updated in the same unit of work. -- **Documentation is not optional.** A feature that is not documented in the README is effectively invisible. Updating the README is part of completing the work, not a follow-up task. -- **The README is authoritative.** If the README and the code disagree, the README is out of date and must be corrected — but it remains the intended source of truth. - -## What belongs in the README - -Include what is relevant. Not every repository needs every section. - -| Section | Purpose | -| -------------------- | -------------------------------------------------------------------------------- | -| **Title** | Repository name as the top-level heading. | -| **Description** | A concise summary (1–3 sentences) of what the repository does and who it is for. | -| **Features / Scope** | A list or prose description of the capabilities the repository provides. | -| **Getting started** | How to install, configure, or use the project for the first time. | -| **Usage** | Examples and explanations of key functionality. Code samples where applicable. | -| **Configuration** | Settings, environment variables, or options the user can control. | -| **Architecture** | High-level overview — folders, components, data flow — for complex repos. | -| **Contributing** | How to contribute, or a link to the organization-level contributing guide. | -| **License** | License type or a link to the LICENSE file. | - -For simple repositories (e.g., a single GitHub Action), a subset is fine — at minimum the title, description, and usage sections. - -## When to update the README - -The README is updated **in the same pull request** that introduces the change. Documentation is part of the work — not a separate follow-up. - -### Update when - -- A new feature, command, function, or capability is added. -- An existing feature changes in behavior, parameters, or output. -- A feature, command, or option is removed or deprecated. -- Installation or setup steps change. -- Configuration options change. -- The project scope or purpose evolves. -- Architecture or folder structure changes significantly. - -### Do not update for - -- Internal refactoring with no user-facing impact. -- Code style or formatting changes. -- CI/CD changes that do not affect usage. -- Dependency updates that do not change behavior. - -## Agent workflow - -When an agent works on a repository, the README sequence is: - -1. **Read the README first** — before reading source code, understand the project context. -2. **Use the README as a guide** — let documented scope and architecture inform where and how to make changes. -3. **Update the README as part of implementation** — same PR, not a follow-up. -4. **Match the existing tone and structure** — heading levels, conventions, and style already present. -5. **Don't delete without reason** — if something is outdated, update it rather than removing it, unless the feature no longer exists. - -## Writing guidelines - -- Write for a reader who has **no prior context**. -- Use clear, direct language. Avoid jargon unless the audience is technical and the term is standard. -- Use examples liberally — a code sample is worth a paragraph. -- Focus on **what** and **how**, not implementation details. Internal design lives in code comments or architecture docs. -- Follow the organization-wide Markdown style. - -## Why the README, and not this docs site - -This docs site (psmodule.io/docs) is the **organization-level** evergreen context — principles, workflow, standards. The README is the **repository-level** evergreen context — what this specific repo is and does. - -Both are required. The docs site explains how PSModule works. The README explains what this repository is. An agent reading the docs site knows the system; an agent reading a README knows the project. diff --git a/src/docs/Ways-of-Working/Review-Etiquette.md b/src/docs/Ways-of-Working/Review-Etiquette.md deleted file mode 100644 index 3edac68..0000000 --- a/src/docs/Ways-of-Working/Review-Etiquette.md +++ /dev/null @@ -1,100 +0,0 @@ -# Review Etiquette - -How to disagree well, how to keep reviews focused, and how to keep the loop converging. - -## For the Reviewer - -### What to assess - -Consider each of the following dimensions when reviewing a PR: - -- **Functional** — Does the code meet the stated needs? -- **Reliability** — Are we confident that the code will run failure-free? -- **Performance** — Is the code as efficient as it can be? -- **Usability** — Consider the user(s) of the service/product we provide; is the experience of high quality with this change? -- **Security** — Are we improving the security posture of the service/product with the changes to the code? Are we worsening it? -- **Maintainability** — Is the architecture good for future maintenance? -- **Standards** — Is the code meeting coding standards for the project and language? - -### Stay in scope - -The PR delivers a specific issue. Suggestions that go beyond that issue are **new issues**, not blocking review comments. File the follow-up and link it from the comment. - -### One concern per comment - -Each thread is a scoped conversation. Bundling multiple unrelated nits into one comment makes it hard to resolve threads cleanly. - -### Be clear about severity - -Use explicit prefixes so the author knows what is blocking: - -- `Blocking:` — must be addressed before merge. -- `Question:` — needs clarification; may or may not lead to a change. -- `Suggestion:` — improvement worth considering; the author can take or leave it with reasoning. -- `Nit:` — small style or preference issue; the author can dismiss freely. - -### Reason from evidence - -Cite the docs, the linter rule, the security advisory, the linked issue's Section 2. "It feels off" is rarely actionable. "This contradicts the decision in #N's Section 2" is. - -### Don't review your own PR publicly - -Self-review is fine and encouraged — but it goes to the terminal as a pre-flight report, not as GitHub comments on your own PR. (And by GitHub rules, you cannot `Request changes` on your own PR — submit a `Comment` review and use a blocking label if needed.) - -### Distinguish bots from humans - -Bot comments (linters, security scanners) tend to be factual. Human comments may carry context the bot can't infer — read them carefully and don't bulk-dismiss. - -## For the Responder (the author) - -### Reply before resolving - -Every resolved thread has a reply explaining the action — what was fixed, why dismissed, which issue picked it up. Bulk-resolving without replies looks like avoidance. - -### Forward progress over discussion - -A valid concern that needs deep design discussion becomes a follow-up issue and a resolved thread, not an open thread that blocks the PR. Open threads are blockers — minimize them. - -### Don't expand the PR - -The Reviewer suggested a thing that's out of scope. It's still out of scope. Reply, file the issue, link, resolve. Don't merge the suggestion in just to be polite. - -### Propagate fixes - -If a reviewer found a problem in one place and the same pattern exists elsewhere, fix it everywhere consistently. A partial fix that leaves identical problems in similar files is incomplete. - -### Test coverage gaps - -When a reviewer finds a real bug existing tests didn't catch, the fix is incomplete without a new or corrected test that closes the gap. Fixing only the source means the next regression is just as silent as this one. - -### Don't bulk-dismiss bot feedback - -Linter and security findings have a reason. Address them or suppress them with explicit justification — don't just silence them. - -## For both sides - -### Tone - -- Impersonal where possible. "This change does X" beats "You did X". -- No sarcasm in writing — it doesn't travel well across time zones, languages, or human-agent boundaries. -- Assume good intent. Both reviewer and author are trying to ship the right thing. - -### Disagreements - -When the Reviewer and Responder genuinely disagree: - -1. Re-state the disagreement plainly in the thread. -2. Reference the relevant doc, decision, or principle. -3. If still stuck, escalate to a human maintainer or file a discussion issue. Don't loop on the same thread. - -### Converge, don't diverge - -Every change in a review round should move the PR closer to merge. Avoid introducing new code that itself needs another review round. If a fix introduces a new design choice, surface it in the response and let the Reviewer accept it before piling further changes on top. - -### Stale comments - -If the code referenced by a comment has been modified since, mention it in the reply. Don't silently let stale comments accumulate as open threads. - -## What this is not - -This is not a process gate. It is **shared etiquette** so the loop is fast, professional, and respectful — across human reviewers, human authors, and the agents working alongside them. diff --git a/src/docs/Ways-of-Working/Workflow.md b/src/docs/Ways-of-Working/Workflow.md deleted file mode 100644 index db91990..0000000 --- a/src/docs/Ways-of-Working/Workflow.md +++ /dev/null @@ -1,148 +0,0 @@ -# Workflow - -How work flows from idea to delivery — and back again. This is the heartbeat of the PSModule ecosystem. - -## The big picture - -Two things run side by side, continuously: - -1. **Context** — keeping issues, decisions, READMEs, and documentation right and evergreen. -2. **Software** — delivering code, tests, and releases. - -Each feeds the other. Software produces signals that require context maintenance. Refined context unblocks the next round of software work. The loop never stops. - -```mermaid -flowchart TD - Usr(["👤 Users\n(wishes, bug reports)"]) - Ext(["🌐 External solutions\n(new APIs, dependency updates,\nplatform changes)"]) - - Usr -->|request| Cap - Ext -->|monitor & detect| Cap - - subgraph CM["Context maintenance"] - Cap[Capture] --> Ref[Refine] --> Pl[Plan] - Pl --> T[simple task] - Pl --> S[sub-issues] - Pl --> CL[checklist] - end - - subgraph SD["Software delivery"] - Bld["Branch → Draft PR → Build → Finalize"] - Bld --> Rev[Review] - Rev -->|fixes needed| Rsp[respond] - Rsp --> Rev - end - - T --> Bld - S --> Bld - CL --> Bld - Rev --> Ops["Run and operate (DevOps + SRE loop)"] - Ops --> Sig["Signals, errors, feedback"] - Sig --> Cap - Ops -->|new release observed| Ext -``` - -## Phases - -### Capture - -A desire for change enters the system. It can come from anywhere: - -- A user request or feature idea. -- A bug report or error signal. -- An observation during a review. -- A dependency update or platform change. - -The goal is to **write it down** — quickly, in a GitHub issue — so it exists for the world to see and "remember". -At this stage, precision is less important than existence. The issue captures the current state, the pain or opportunity, and the desired outcome. - -See [Issue Format § Section 1](Issue-Format.md) for structure. - -### Refine - -Ground the captured desire in reality. Ask: - -- What is the actual problem? (Not the symptom, not the first solution that comes to mind.) -- Who is affected and how? -- What does "done" look like from - 1. the user's perspective? - 2. the maintainer's perspective? -- Are there constraints, dependencies, or prior decisions that matter? - -This may involve questions in issue comments, interactive discussion, or research. -The goal is **shared understanding** — everyone (humans and agents) agrees on what the real problem is and what the outcome should be. - -### Plan - -Turn the refined understanding into actionable work: - -- **Decisions** — what approach will we take? What trade-offs are we making? Document them in the issue. -- **Decomposition** — if the work is large, break it into sub-issues. Each sub-issue should be deliverable in a single pull request. -- **Checklist** — for a single task, list the concrete steps in the issue body. - -The plan is the contract. It drives implementation. - -See [Issue Format § Sections 2–3](Issue-Format.md), [Issue Hierarchy](Issue-Hierarchy.md). - -### Build - -Execute the plan: - -1. **Branch** — create a branch (and [worktree](Git-Worktrees.md)) for the issue. -2. **Draft PR** — push early and open a draft pull request. Link it to the issue. This makes progress visible and attaches CI from the start. -3. **Implement** — work through the checklist. One logical change per commit. Update the issue as each task completes. -4. **Test locally** — don't push known failures to CI. Push work as far inward as it can go. - -See [Commit Conventions](Commit-Conventions.md), [PR Format](PR-Format.md). - -### Review - -Every change gets a second perspective: - -- Does the PR deliver what the linked issue asks for? -- Does it follow the project's standards and conventions? -- Are there security concerns or undiscussed decisions? -- Is the code clear and maintainable? - -Feedback is processed one thread at a time: read → evaluate → fix → reply → resolve. - -See [Review Etiquette](Review-Etiquette.md). - -### Ship - -When all tasks are complete, CI is green, and review is approved: - -1. Update the PR title and description as a user-facing release note. -2. Apply the correct labels (Major, Minor, Patch, etc.). -3. Mark ready for review (or merge, depending on the project's flow). - -The PR description becomes the release note. Write it for end users, not reviewers. - -See [PR Format](PR-Format.md). - -### Operate - -> You build it, you run it. - -After merge, the system is live. Monitor, observe, respond to signals. When something breaks or an opportunity appears — the loop starts again at **Capture**. - -## Three horizons of planning - -Planning happens at different time horizons and levels of detail: - -| Level | Now | Next | Later | -| ---------- | -------------------- | ------------- | -------------- | -| Conceptual | Vision delivered now | Vision next | Vision later | -| Logical | Approach now | Approach next | Approach later | -| Detailed | Tasks in flight | Tasks ready | Tasks framed | - -- **Now / Next / Later** are time horizons without firm dates. -- **Conceptual / Logical / Detailed** are levels of fidelity. - -Detail increases as work moves from Later toward Now. - -- A single task lives in **Now / Detailed**. -- A product backlog item lives between **Now / Logical** and **Next / Detailed**. -- An epic spans **Now → Next → Later** at **Conceptual / Logical** fidelity. - -This workflow follows the [Human–agent coexistence](Principles.md#human-agent-coexistence) principle — it is designed for humans first, with agents joining the same process rather than running a parallel one. diff --git a/src/docs/Ways-of-Working/continuous-x-and-continuous-ai.md b/src/docs/Ways-of-Working/continuous-x-and-continuous-ai.md deleted file mode 100644 index 711c8a0..0000000 --- a/src/docs/Ways-of-Working/continuous-x-and-continuous-ai.md +++ /dev/null @@ -1,156 +0,0 @@ -# Continuous X Practices, Continuous AI, and the Microsoft DevOps Dojo - -## 1. The "Continuous X" Practices - -### Microsoft DevOps Dojo's eight pillars (White Belt) - -The cleanest authoritative taxonomy. From [DevOps Dojo White Belt Foundation](https://learn.microsoft.com/en-us/training/paths/devops-dojo-white-belt-foundation/): - -| # | Practice | What it covers | -| --- | ---------- | ---------------- | -| 1 | Continuous Planning | Lean product, hypothesis-driven dev, backlog management, OKRs | -| 2 | Continuous Integration | Trunk-based dev, automated build & test on every commit | -| 3 | Continuous Delivery | Every commit potentially releasable; automated pipeline to prod | -| 4 | Continuous Quality | Test pyramid, shift-left testing, code review, static analysis | -| 5 | Continuous Security | Shift-left security, SAST/DAST/SCA, secrets, supply chain | -| 6 | Continuous Operations | SRE, observability, SLOs, incident response, on-call | -| 7 | Continuous Collaboration | ChatOps, docs-as-code, transparent comms, shared ownership | -| 8 | Continuous Improvement | Kaizen, retros, blameless postmortems, value-stream mapping | - -### Full inventory with provenance - -| Practice | Origin / canonical source | -| ---------- | -------------------------- | -| **Continuous Integration** | Coined in Grady Booch's 1991 method; popularised by XP and [Martin Fowler's 2006 article](https://martinfowler.com/articles/continuousIntegration.html). | -| **Continuous Delivery** | Jez Humble & David Farley, [*Continuous Delivery*](https://continuousdelivery.com/), 2010. | -| **Continuous Deployment** | Every passing build deploys to prod with no human gate (vs. CD which only makes it *deployable*). | -| **Continuous Testing** | Test throughout the pipeline plus in production (synthetic, canary analysis). | -| **Continuous Verification** | Netflix's term for chaos-engineering-style continuous resilience validation. Rosenthal & Jones, [*Chaos Engineering*](https://www.oreilly.com/library/view/chaos-engineering/9781492043850/), O'Reilly. | -| **Continuous Monitoring → Continuous Observability** | Shift from dashboards of knowns to ad-hoc querying of unknowns. [Honeycomb's Observability Manifesto](https://www.honeycomb.io/blog/observability-a-manifesto). | -| **Continuous Feedback** | Right-to-left flow from prod → dev. DevOps Second Way (*Phoenix Project*). | -| **Continuous Improvement** | Toyota *kaizen*; Deming PDCA cycle. | -| **Continuous Learning** | DevOps Third Way (Kim, *Phoenix Project*). | -| **Continuous Security / DevSecOps** | OWASP; [DoD Enterprise DevSecOps Reference Design](https://dodcio.defense.gov/Portals/0/Documents/DoD%20Enterprise%20DevSecOps%20Reference%20Design%20v1.0_Public%20Release.pdf). | -| **Continuous Compliance** | Compliance-as-code: Chef InSpec, OPA, AWS Config. | -| **Continuous Configuration Automation (CCA)** | Gartner term covering Ansible/Puppet/Chef/Salt. | -| **Continuous Inspection** | SonarSource's term for always-on code-quality scanning. [docs.sonarsource.com](https://docs.sonarsource.com/). | -| **Continuous Profiling** | Always-on production profiling. Pyroscope/Grafana, Polar Signals, Google-Wide Profiling paper (2010). | -| **Continuous Documentation / docs-as-code** | Write the Docs community; treat docs like code. | -| **Continuous Experimentation** | A/B testing, hypothesis-driven dev. Kohavi et al., [*Trustworthy Online Controlled Experiments*](https://experimentguide.com/), 2020. | -| **Continuous Discovery** | Teresa Torres, [*Continuous Discovery Habits*](https://www.producttalk.org/continuous-discovery-habits/), 2021. | -| **Continuous Architecture** | Erder & Pureur, *Continuous Architecture in Practice*, 2021. | -| **Continuous Refactoring** | XP practice; Fowler's [*Refactoring*](https://martinfowler.com/books/refactoring.html). | -| **Continuous Reliability** | Vendor-popularised (Catchpoint, Gremlin); convergence of SRE + chaos + observability. | -| **Continuous Code Review** | Modern PR workflows + always-on reviewers. | -| **Continuous Training (CT)** in MLOps | Google's [MLOps Levels 1–2](https://cloud.google.com/architecture/mlops-continuous-delivery-and-automation-pipelines-in-machine-learning) — automatic retraining on fresh data. | - ---- - -## 2. Continuous AI - -**Canonical source:** [GitHub Next — Continuous AI](https://githubnext.com/projects/continuous-ai/), published June 2025 by Eddie Aftandilian, Peli de Halleux, Russell Horton, Don Syme. - -### Definition (verbatim) -> "All uses of automated AI to support software collaboration on any platform." - -Positioned explicitly as the AI-era counterpart to CI/CD: *"Just as CI/CD transformed software development by automating integration and deployment, Continuous AI covers the ways in which AI can be used to automate and enhance collaboration workflows."* - -GitHub explicitly does **not** claim ownership of the term — it's a label for the industry, not a product. - -### Seven characteristics (GitHub Next's taxonomy) -Continuous AI tasks are: **automatable, repetitive, collaborative, integrated, auditable, event-triggered**, and have **many variants**. - -### GitHub Next's example workflows -- **Continuous Documentation** — docs in sync with code automatically -- **Continuous Code Improvement** — comments, tests, small refactors -- **Continuous Triage** — label/summarise/respond to issues in natural language -- **Continuous Summarization** — rolling summaries of project activity -- **Continuous Fault Analysis** — auto-explain failed CI runs -- **Continuous Quality** — LLM-driven quality analysis -- **Continuous Team Motivation** — PRs into poetry/zines/podcasts (the social layer) -- **Continuous Accessibility** — auto-check & improve a11y - -### Continuous AI vs. its cousins - -| Term | What it is | -| ------ | ----------- | -| **Continuous AI** | AI participating *in* the SDLC continuously (review, docs, triage, fault analysis). The AI is the actor. | -| **MLOps** | CI/CD/CT *for* ML models — training, evaluation, deployment, monitoring. The model is the product. | -| **LLMOps** | MLOps specialised for LLM apps: prompt versioning, evals, retrieval, guardrails, cost/latency monitoring. | -| **AIOps** | AI/ML applied to IT operations — anomaly detection, alert correlation, RCA. Gartner term, ~2017. | - -### How Continuous AI augments each Continuous X practice - -| Traditional practice | Continuous-AI augmentation | Example tools (2025) | -| --------------------- | --------------------------- | ---------------------- | -| Continuous Integration | AI summarises broken builds; suggests fixes | GitHub Copilot Workspace, Sweep | -| Continuous Delivery | Agents drive multi-step deploys; AI-authored release notes | GitHub Copilot agents, Devin | -| Continuous Testing | Test generation, flaky-test detection, auto-repair | Diffblue, Qodo (CodiumAI), Meta TestGen-LLM | -| Continuous Quality | LLM PR review beyond linters | CodeRabbit, Greptile, Graphite Diamond, Copilot review | -| Continuous Security | LLM-aware SAST, auto-remediation PRs | Snyk DeepCode, Semgrep Assistant, Copilot Autofix | -| Continuous Operations | "AI SRE" — autonomous triage, RCA, runbook execution | Resolve.ai, Cleric, PagerDuty AIOps, Rootly AI | -| Continuous Documentation | Docs stay in sync with code | Mintlify, GitHub Next *Continuous Documentation* | -| Continuous Code Review | Always-on AI reviewer | CodeRabbit, Greptile, Copilot review | -| Continuous Refactoring | Background agents propose refactors | Cursor background agents, Sourcegraph Cody, Grit.io | -| Continuous Triage | Issue labelling, dedup, summarisation | GitHub Models + Actions recipes, Linear AI | -| Continuous Improvement | Auto-postmortems, retro summaries | incident.io, Rootly, Jeli (Atlassian) | -| Continuous Discovery | LLM synthesis of user research | Dovetail AI, Maze AI | -| Continuous Training (MLOps) | Pre-existed; now intersects with eval-driven LLM dev | Vertex AI, Databricks, Weights & Biases | - -### What structurally changes - -- **Evals are the new tests.** For AI features, regression suites are eval suites — graded by LLM judges or humans. Eval drift = test failure. -- **Pipelines gain non-deterministic actors.** Every Continuous AI step needs auditability: which agent, which model version, which prompt, which tools, what did it touch. -- **Cost and runaway risk.** Traditional CI steps have bounded cost; agentic steps can recurse. Need budgets, timeouts, concurrency caps. -- **Prompt injection becomes a CI/CD threat.** Untrusted issue text, PR descriptions, error messages, third-party docs become attack surfaces when an agent reads them. -- **Governance.** Expect "AI-generated change" to need provenance equivalent to a signed commit. SOC2/ISO27001/regulators catching up. - -### Tooling stack referenced by GitHub Next -- [GitHub Actions](https://github.com/features/actions) -- [GitHub Models](https://github.com/features/models) -- [GenAIScript (Microsoft)](https://microsoft.github.io/genaiscript/) -- [Datasette `llm`](https://llm.datasette.io/) -- [GitHub Agentic Workflows](https://githubnext.com/projects/agentic-workflows/) — sister project at GitHub Next -- [The Agentics](https://github.com/githubnext/agentics/) — example workflows - ---- - -## 3. Microsoft DevOps Dojo — Status - -**Status:** alive but dormant. White Belt remains a real Microsoft Learn path; higher belts are blog posts; GitHub org quiet since late 2022. - -### History -Started ~2018–2019 inside Microsoft (catalysed by a 2019 conversation with German CIOs); grew into a cross-org community spanning Services, Customer Success, Digital Advisory, and product groups. Public face was largely **April Edwards** (Senior Cloud Advocate). Authoritative intro: [*Intro of DevOps Dojo*](https://devblogs.microsoft.com/devops/intro-of-devops-dojo/) on Azure DevOps Blog (July 2022). - -### Belt curriculum -- **White Belt** — standardised DevOps fundamentals — *only one with a formal Microsoft Learn path* -- **Orange Belt** — scaled DevOps (enterprise/program/portfolio) — blog only -- **Green Belts** — domain lenses (e.g. UX/Accessibility) — blog only -- **Black Belt** — data-driven, intelligent DevOps for executives — never published - -Four pillars: Culture & Mindset, Lean Product, Architecture, Technology. - -### Where the content lives today - -**Microsoft Learn — White Belt (six modules):** -- [DevOps Dojo White Belt Foundation](https://learn.microsoft.com/en-us/training/paths/devops-dojo-white-belt-foundation/) - -**Azure DevOps Blog (the deeper belts):** -- [Intro of DevOps Dojo](https://devblogs.microsoft.com/devops/intro-of-devops-dojo/) -- [People & Teams (Orange)](https://devblogs.microsoft.com/devops/devops-dojo-people-teams/) -- [UX/Accessibility (Green)](https://devblogs.microsoft.com/devops/devops-dojo-ux-accessibility/) -- [Culture and Mindset](https://devblogs.microsoft.com/devops/devops-dojo-culture-and-mindset/) -- [Experiential Learning](https://devblogs.microsoft.com/devops/devops-dojo-experiential-learning/) -- [Lean Product Part 1 / Part 2](https://devblogs.microsoft.com/devops/devops-dojo-lean-product-part-1/) - -**DevOps Lab video series:** [learn.microsoft.com/shows/devops-lab](https://learn.microsoft.com/en-us/shows/devops-lab/) - -**GitHub:** [github.com/microsoftdevopsdojo](https://github.com/microsoftdevopsdojo) — sparse, last meaningful activity Oct 2022. - -### What to use today -1. **Dojo White Belt** on Learn — for the Continuous X scaffolding -2. **[Evolve your DevOps practices](https://learn.microsoft.com/en-us/training/paths/evolve-your-devops-practices/)** — practical follow-on -3. **[ISE Engineering Fundamentals Playbook](https://microsoft.github.io/code-with-engineering-playbook/)** — Microsoft's public, actively-maintained engineering playbook. The de facto modern equivalent. -4. **[AZ-400 Enterprise DevOps](https://learn.microsoft.com/en-us/credentials/certifications/devops-engineer/)** — certification track - -The ISE Playbook is the more living artifact — updated regularly, public PRs welcome, covers similar ground without the belt theatre. diff --git a/src/docs/Ways-of-Working/development-practices.md b/src/docs/Ways-of-Working/development-practices.md deleted file mode 100644 index 40ce90e..0000000 --- a/src/docs/Ways-of-Working/development-practices.md +++ /dev/null @@ -1,85 +0,0 @@ -# Development Practices - -How we work on this team. Short, opinionated, and meant to be argued with — if a practice stops serving us, we change it in a retro. - ---- - -## 1. How we think - -**Deliver value, not output.** Shipping code is not the goal. Changing outcomes for customers is. - -- **Customer first.** Every story answers: who is this for, and what changes for them? -- **Small batches.** Smaller changes are safer, faster to review, and faster to learn from. If a story takes more than a few days, split it. -- **Optimize the whole.** A local win that slows the next team down is a loss. Think in flow, not silos. -- **Build quality in.** We do not "add testing later" or "harden it in hardening sprint." Quality is a property of how we work, not a phase. -- **Decide reversibly.** Prefer decisions that are cheap to undo. For one-way doors, slow down and write it down. - ---- - -## 2. How we plan - -**Flow over utilization.** A busy team is not the same as a productive team. - -- **One backlog, ranked.** The top is always the next most valuable thing. No parallel priority lists. -- **Thin vertical slices.** Each story delivers end-to-end value — UI through to data. No "backend-only" stories that wait weeks for a frontend. -- **Limit WIP.** Finish before you start. Work-in-progress is inventory; inventory is risk. -- **Definition of Ready / Done are contracts.** Ready = small enough, clear enough, testable. Done = merged, deployed, observable, documented. -- **Estimate to align, not to commit.** Sizing is a conversation tool. If we need a date, we forecast from throughput, not from gut feel. -- **Retro every two weeks, minimum.** One concrete change per retro, owned by a person, checked next retro. - ---- - -## 3. How we build - -**Simple, tested, readable — in that order of argument-winning power.** - -- **TDD where it pays.** Red-green-refactor for logic with branching, edge cases, or money. Not dogma for trivial glue. -- **Pair or review, always.** No code reaches `main` without a second pair of eyes. Pairing counts as review. -- **Trunk-based.** Short-lived branches, merged daily. Feature flags over long-lived branches. -- **SOLID, applied with judgement.** Especially: single responsibility, and depend on abstractions at module boundaries. Don't invent interfaces you have one implementation of. -- **DRY the knowledge, not the code.** Two things that look the same but change for different reasons are not duplication. Premature deduplication is worse than repetition. -- **YAGNI.** Build for the requirement in front of you. Extensibility you don't need is complexity you pay for. -- **Clean Code basics.** Names reveal intent. Functions do one thing. Comments explain why, not what. Delete dead code. -- **Refactor continuously.** Leave the code better than you found it. Refactoring is part of the story, not a separate ticket. - ---- - -## 4. How we ship - -**You build it, you run it.** The team that writes the code owns it in production. - -- **Everything in version control.** Code, infra, pipelines, dashboards, runbooks. -- **CI on every commit.** Build, lint, test, security scan. Red build blocks everyone — we fix it first. -- **CD by default.** `main` is always deployable. Deploys are boring, frequent, and automated. -- **Feature flags for risk.** Decouple deploy from release. Roll forward, not back. -- **Observability is a feature.** Logs, metrics, traces, and a dashboard ship with the service. If you can't see it, you don't own it. -- **Alert on symptoms, not causes.** Page on customer impact. Everything else is a ticket. -- **Secure by default.** Least privilege, secrets in a vault, dependencies patched, threats modelled for new surfaces. -- **Runbooks for the top 5 alerts.** Written by the team, tested in game days. - ---- - -## 5. How we improve - -**Learning is the work.** The service will outlive any single feature we build. - -- **Blameless postmortems.** For every incident that hurt a customer or woke someone up. Output: actions with owners, not blame. -- **Measure what matters.** Lead time, deploy frequency, change fail rate, MTTR (the DORA four). Plus whatever customer metric this service moves. -- **Kill your darlings.** Deprecate and delete code, features, dashboards, and meetings that stopped paying rent. -- **Share the learning.** Demos, brown bags, ADRs. If only one person knows how it works, that's a bug. - ---- - -## Principles we borrow from - -- **Agile Manifesto, Scrum, Kanban, XP** — iteration, flow, TDD, pairing, collective ownership. -- **Lean Product Development** — small batches, flow, limit WIP, build quality in, defer commitment. -- **DevOps / DevOps Dojo** — you build it you run it, automation, measurement, blameless culture. -- **SOLID, DRY, YAGNI, Clean Code** — keep the inside of the code honest. -- **DORA** — measure delivery performance. - ---- - -## How this document works - -This is version 0. We review it every quarter and after any incident that exposes a gap. Propose changes in a PR; we decide in a retro. diff --git a/src/docs/Ways-of-Working/devops-reference.md b/src/docs/Ways-of-Working/devops-reference.md deleted file mode 100644 index 26993d9..0000000 --- a/src/docs/Ways-of-Working/devops-reference.md +++ /dev/null @@ -1,160 +0,0 @@ -# DevOps Principles and Practices — Reference Guide - -A curated synthesis of authoritative sources, frameworks, and practices. - ---- - -## 1. Essential Reading List - -### The Canon (Books) - -| # | Title | Author(s) | Year | Why it matters | -| --- | ------- | ----------- | ------ | ---------------- | -| 1 | **The Phoenix Project** | Gene Kim, Kevin Behr, George Spafford | 2013 | The novel that introduced DevOps to mainstream. Source of the Three Ways. [itrevolution.com/product/the-phoenix-project](https://itrevolution.com/product/the-phoenix-project/) | -| 2 | **The Unicorn Project** | Gene Kim | 2019 | Sequel from the developer's perspective; flow state, psychological safety, Five Ideals. | -| 3 | **The DevOps Handbook** (2nd ed.) | Gene Kim, Jez Humble, Patrick Debois, John Willis | 2016/2021 | Practical companion to Phoenix Project. The reference implementation guide. | -| 4 | **Continuous Delivery** | Jez Humble, David Farley | 2010 | Foundational technical text on CI/CD and deployment pipelines. [continuousdelivery.com](https://continuousdelivery.com/) | -| 5 | **Accelerate** | Forsgren, Humble, Kim | 2018 | The science: rigorous research showing which practices actually drive performance. Origin of DORA metrics. | -| 6 | **Team Topologies** | Matthew Skelton, Manuel Pais | 2019 | The four team types and cognitive load as a design constraint. [teamtopologies.com](https://teamtopologies.com/) | -| 7 | **Lean Software Development** | Mary & Tom Poppendieck | 2003 | Lean manufacturing principles applied to software. | -| 8 | **Out of the Crisis** | W. Edwards Deming | 1982 | Foundational systems thinking; 14 Points. The intellectual root of DevOps. | -| 9 | **The Goal** | Eliyahu Goldratt | 1984 | Theory of Constraints. The novel format Kim borrowed for Phoenix Project. | - -### Google SRE Books — All Free Online - -All available at **[sre.google/books](https://sre.google/books/)** - -- **Site Reliability Engineering** (2016) — How Google runs production. SLOs, error budgets, toil, on-call, postmortems. [sre.google/sre-book/table-of-contents](https://sre.google/sre-book/table-of-contents/) -- **The Site Reliability Workbook** (2018) — Practical implementation. [sre.google/workbook/table-of-contents](https://sre.google/workbook/table-of-contents/) -- **Building Secure & Reliable Systems** (2020) — DevSecOps and resilient design. [google.github.io/building-secure-and-reliable-systems](https://google.github.io/building-secure-and-reliable-systems/raw/toc.html) - ---- - -## 2. Core Principles - -### The Three Ways (from *The Phoenix Project*) - -1. **Flow** — Optimize the whole system, not silos. Reduce batch sizes, never pass defects downstream, build quality in early. → CI/CD, trunk-based dev, feature flags, WIP limits. -2. **Feedback** — Amplify feedback loops right-to-left (ops → dev). → Observability, monitoring, SLOs, postmortems. -3. **Continual Learning** — Culture of experimentation, blameless failure, deliberate practice. → Postmortems, chaos engineering, innovation time, game days. - -### Other Foundational Principles - -- **"You build it, you run it"** (Werner Vogels, Amazon) — Devs own their services in production. Shared on-call. -- **Automation everywhere** — CI/CD, IaC, automated testing, security, compliance. Eliminate toil. -- **Small batch sizes & trunk-based development** — Short-lived branches (<1 day), feature flags decouple deploy from release. [trunkbaseddevelopment.com](https://trunkbaseddevelopment.com/) -- **Observability over monitoring** — Three pillars: logs, metrics, traces. Designed-in, not bolted on. [Honeycomb's Observability Manifesto](https://www.honeycomb.io/blog/observability-a-manifesto) -- **Error budgets & SLOs** — Reliability is a feature with a cost. Aligns dev velocity and ops stability. -- **Blameless postmortems** — Learning > blame. Focus on systems, not people. -- **Shift-left security (DevSecOps)** — SAST, dependency scanning, secret scanning, IaC scanning in CI. -- **Infrastructure as Code** — Version-controlled, peer-reviewed infra. Terraform, Pulumi, Kubernetes manifests + GitOps. - ---- - -## 3. Frameworks Worth Knowing - -### DORA — Four Key Metrics -The evidence-based standard for DevOps performance. Source: Forsgren/Humble/Kim research, now part of Google Cloud. - -| Metric | What it measures | Elite performance | -| -------- | ------------------ | ------------------- | -| **Deployment Frequency** | How often you deploy to prod | Multiple per day / on-demand | -| **Lead Time for Changes** | Commit → production | < 1 hour | -| **Change Failure Rate** | % of deploys causing problems | 0–15% | -| **Mean Time to Restore** | Recovery from prod incidents | < 1 hour | - -A fifth metric — **Reliability** — was added in recent reports. - -- Latest research: [dora.dev/research](https://dora.dev/research/) -- Annual State of DevOps Report: [cloud.google.com/devops/state-of-devops](https://cloud.google.com/devops/state-of-devops) - -### SPACE — Developer Productivity (Forsgren et al., 2021) -DORA measures *delivery*; SPACE measures *productivity* holistically. Five dimensions: **S**atisfaction, **P**erformance, **A**ctivity, **C**ommunication, **E**fficiency. No single metric works — need balance. [space-framework.com](https://space-framework.com/) - -### CALMS — DevOps Self-Assessment (Jez Humble) -**C**ulture, **A**utomation, **L**ean, **M**easurement, **S**haring. Atlassian writeup: [atlassian.com/devops/frameworks/calms-framework](https://www.atlassian.com/devops/frameworks/calms-framework) - -### Team Topologies — The Four Team Types -1. **Stream-aligned** — Owns a value stream end-to-end. The default team. -2. **Platform** — Builds the IDP that stream-aligned teams consume. -3. **Enabling** — Temporary coaches helping stream-aligned teams adopt new capabilities. -4. **Complicated-subsystem** — Deep specialists (rarely needed). - -Plus three interaction modes: collaboration, X-as-a-service, facilitating. **Cognitive load** is the explicit design constraint. - ---- - -## 4. How Good Teams Operate - -### Service Ownership -One team owns a service from concept to retirement: code, deploys, on-call, SLOs, runbooks, DR, deprecation. - -### On-Call Health Markers -- < 2 pages/week per engineer -- MTTR < 30 min for typical incidents -- Alerts are actionable (business-level, not "CPU > 80%") -- Runbook for every alert -- Clear escalation policy + secondary on-call -- Time off after major incidents - -### Incident Response -- Incident commander coordinates; scribe documents -- Real-time war room (Slack channel + bridge) -- Status updates every 15–30 min -- Postmortem within 3–5 days, blameless, public, with tracked action items -- Reference: [SRE Book — Postmortem Culture](https://sre.google/sre-book/postmortem-culture/) - -### Release Engineering -- **Canary** — 5% → 25% → 100%, with auto-rollback on metric breach -- **Blue/green** — Atomic cutover with instant rollback -- **Feature flags** — Decouple deploy from release; LaunchDarkly, Unleash, Split -- **Progressive delivery** — Combine canary + flags + experimentation - -### Observability Stack (one common shape) -- Logs: ELK, Loki, Datadog, Honeycomb -- Metrics: Prometheus + Grafana, Datadog, New Relic -- Traces: Jaeger, Tempo, Honeycomb, Datadog APM -- All correlated via trace ID propagated through services - -### Toil Reduction (SRE 50% rule) -SREs spend ≤ 50% on toil; the rest on engineering away the toil. [SRE Book — Eliminating Toil](https://sre.google/sre-book/eliminating-toil/) - -### Platform Engineering (the modern evolution) -Internal Developer Platforms (IDPs) are how mature orgs reduce cognitive load on stream-aligned teams. Self-service deploys, golden paths, paved roads. Communities: -- [platformengineering.org](https://platformengineering.org/) -- [humanitec.com](https://humanitec.com/) — research and benchmarks -- CNCF TAG App Delivery — [github.com/cncf/tag-app-delivery](https://github.com/cncf/tag-app-delivery) - ---- - -## 5. Where to Go Deeper - -### Authoritative organizations -- **IT Revolution Press** — Gene Kim's publisher; DevOps Enterprise Summit talks (free): [itrevolution.com](https://itrevolution.com/) -- **Google SRE** — [sre.google](https://sre.google/) -- **DORA / Google Cloud** — [dora.dev](https://dora.dev/) -- **CNCF** — Cloud-native landscape and definitions: [cncf.io](https://www.cncf.io/), [landscape.cncf.io](https://landscape.cncf.io/) -- **ThoughtWorks Technology Radar** — Quarterly opinionated assessment: [thoughtworks.com/radar](https://www.thoughtworks.com/radar) - -### Vendor guides (well-written even if biased) -- Atlassian DevOps Guide: [atlassian.com/devops](https://www.atlassian.com/devops) -- GitLab — *The Remote DevOps Lifecycle*: [about.gitlab.com/topics/devops](https://about.gitlab.com/topics/devops/) -- GitHub — *Well-Architected* and DevOps guides: [resources.github.com/devops](https://resources.github.com/devops/) -- AWS DevOps: [aws.amazon.com/devops](https://aws.amazon.com/devops/) -- Microsoft DevOps Resource Center: [learn.microsoft.com/en-us/devops](https://learn.microsoft.com/en-us/devops/) - -### Voices to follow -- **Charity Majors** (Honeycomb) — Observability. Blog: [charity.wtf](https://charity.wtf/) -- **Liz Fong-Jones** — SRE/observability practitioner -- **Gene Kim** — DevOps movement, IT Revolution -- **Jez Humble** — CD, Accelerate co-author -- **Nicole Forsgren** — DORA/SPACE research lead -- **Kelsey Hightower** — Cloud-native pragmatism -- **Matthew Skelton & Manuel Pais** — Team Topologies -- **John Willis** — Deming, DevOps history - -### Conferences worth watching (talks free on YouTube) -- DevOps Enterprise Summit (DOES) -- SREcon (USENIX) -- KubeCon + CloudNativeCon -- QCon diff --git a/src/docs/Ways-of-Working/index.md b/src/docs/Ways-of-Working/index.md deleted file mode 100644 index b1adc5d..0000000 --- a/src/docs/Ways-of-Working/index.md +++ /dev/null @@ -1,22 +0,0 @@ -# Ways of Working - -Shared conventions for how work happens across the PSModule ecosystem — for humans and agents alike. - -This section documents the principles, processes, and norms that every contributor follows. Whether you're opening an issue, writing a commit message, reviewing a pull request, or planning a feature — the answer is here. - -## What's covered - -- **[Workflow](Workflow.md)** — How work flows from idea to delivery and back again. The phases, the loop, and how they connect. -- **[Principles](Principles.md)** — The foundational beliefs and product mindset that drive every decision. -- **[Goal-Setting Framework](Goal-Setting.md)** — Mission, OKRs, and Initiatives — how strategic direction connects to work in repositories. -- **[Issue Format](Issue-Format.md)** — The three-section issue structure, formatting rules, and labels. -- **[Issue Hierarchy](Issue-Hierarchy.md)** — Epic / PBI / Task — the three operational levels tracked via GitHub sub-issues. -- **[PR Format](PR-Format.md)** — Pull request title, description, change types, and labels. -- **[Commit Conventions](Commit-Conventions.md)** — How we write commit messages. -- **[Review Etiquette](Review-Etiquette.md)** — Tone, scope, severity prefixes, and how to disagree well. -- **[Git Worktrees](Git-Worktrees.md)** — Bare-clone + worktree layout for parallel, conflict-free development. -- **[README-Driven Context](Readme-Driven-Context.md)** — Why the README is the front door and the source of truth. - -## Who this is for - -Everyone. If you contribute to a PSModule project — by code, review, issue, or discussion — these are the norms you follow. Agents follow them too; they read these pages as context before acting. diff --git a/src/docs/index.md b/src/docs/index.md index 8034636..ede2a05 100644 --- a/src/docs/index.md +++ b/src/docs/index.md @@ -31,7 +31,7 @@ The framework is two things in one: a collection of reusable PowerShell modules, We empower PowerShell-savvy developers to effortlessly transform their ideas into impactful solutions, automating the repetitive tasks so developers — whether consumers or contributors — can concentrate on coding without distractions. -Where we are headed is tracked as [objectives and initiatives](Ways-of-Working/Goal-Setting.md). +Where we are headed is tracked as [objectives and initiatives](https://msxorg.github.io/docs/Ways-of-Working/Goal-Setting/). ## Products and projects we focus on diff --git a/src/zensical.toml b/src/zensical.toml index 581a4ec..1ecfaf1 100644 --- a/src/zensical.toml +++ b/src/zensical.toml @@ -64,19 +64,6 @@ nav = [ {"GitHub Copilot Customization" = "Solutions/GitHub-Copilot-Customization-Architecture.md"}, {"Self-Service System" = "Solutions/Self-service-system.md"}, ]}, - {"Ways of Working" = [ - "Ways-of-Working/index.md", - {"Workflow" = "Ways-of-Working/Workflow.md"}, - {"Principles" = "Ways-of-Working/Principles.md"}, - {"Goal-Setting Framework" = "Ways-of-Working/Goal-Setting.md"}, - {"Issue Format" = "Ways-of-Working/Issue-Format.md"}, - {"Issue Hierarchy" = "Ways-of-Working/Issue-Hierarchy.md"}, - {"PR Format" = "Ways-of-Working/PR-Format.md"}, - {"Commit Conventions" = "Ways-of-Working/Commit-Conventions.md"}, - {"Review Etiquette" = "Ways-of-Working/Review-Etiquette.md"}, - {"README-Driven Context" = "Ways-of-Working/Readme-Driven-Context.md"}, - {"Git Worktrees" = "Ways-of-Working/Git-Worktrees.md"}, - ]}, {"Dictionary" = [ "Dictionary/index.md", ]},