diff --git a/.github/actions/update-index/src/Helper.psm1 b/.github/actions/update-index/src/Helper.psm1 index 30ed03a..dbba6f8 100644 --- a/.github/actions/update-index/src/Helper.psm1 +++ b/.github/actions/update-index/src/Helper.psm1 @@ -229,7 +229,7 @@ $moduleTableRows "@ - Update-MDSection -Path '.\src\docs\PowerShell\Modules\index.md' -Name 'MODULE_LIST' -Content $moduleTable + Update-MDSection -Path '.\src\docs\Modules\Catalog\index.md' -Name 'MODULE_CATALOG' -Content $moduleTable } function Update-FunctionAppList { diff --git a/.github/actions/update-index/src/main.ps1 b/.github/actions/update-index/src/main.ps1 index c49d528..c2d68fb 100644 --- a/.github/actions/update-index/src/main.ps1 +++ b/.github/actions/update-index/src/main.ps1 @@ -1,6 +1,6 @@ Import-Module -Name (Join-Path $PSScriptRoot 'Helper.psm1') Show-RepoList -Update-ActionList -Update-FunctionAppList +# Update-ActionList +# Update-FunctionAppList Update-ModuleList diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..3884664 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1 @@ +Follow the instructions in [AGENTS.md](../AGENTS.md). diff --git a/.github/linters/.markdown-lint.yml b/.github/linters/.markdown-lint.yml index 7d96392..db8977f 100644 --- a/.github/linters/.markdown-lint.yml +++ b/.github/linters/.markdown-lint.yml @@ -8,19 +8,20 @@ ############### # Rules by id # ############### -MD004: false # Unordered list style +MD004: false # Unordered list style MD007: - indent: 2 # Unordered list indentation + indent: 2 # Unordered list indentation MD013: - line_length: 3000 # Line length + line_length: 3000 # Line length +MD025: false # Allow front-matter title + visible H1 on docs pages MD026: - punctuation: ".,;:!。，；:" # List of not allowed -MD029: false # Ordered list item prefix -MD033: false # Allow inline HTML -MD036: false # Emphasis used instead of a heading -MD041: false # First line in file should be a top level heading, PULL_REQUEST_TEMPLATE.md is an exception + punctuation: '.,;:!。，；:' # List of not allowed +MD029: false # Ordered list item prefix +MD033: false # Allow inline HTML +MD036: false # Emphasis used instead of a heading +MD041: false # First line in file should be a top level heading, PULL_REQUEST_TEMPLATE.md is an exception ################# # Rules by tags # ################# -blank_lines: false # Error on blank lines +blank_lines: false # Error on blank lines diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..e9818ea --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,29 @@ +# Agents + +## Main directive + +Everything is a work in progress and can be updated and improved. +If you find a problem, fix it if it's small; otherwise, register it as an issue in the respective repo. + +## Install the ecosystem + +1. Create a folder in the home directory called `.msx/PSModule`: +2. Clone the ecosystem locally: + 1. — requires PRs to be updated. + - Clone as bare and use worktrees. + - Create a worktree for all branches - worktree = name of the branch. + 2. — work directly towards main. + - Simple clone, only main. + +To install: + Clone the repos in the users home folder under a sub-folder named `.msx/PSModule`. +- Set configs locally to each of these repos using the GitHub username and email. + +## Working with the ecosystem + +1. Get to know this repo first: + - [README](README.md) for what this repository is and how it builds. + - [CONTRIBUTING](CONTRIBUTING.md) for how to contribute and the review process. +2. Read the `.msx/PSModule/main/docs` - start with the index to get an overview of what is here. +3. Read the `.msx/PSModule/memory` - start with the index to get an overview of what is here. Use this while working - commit your memories here for work inside the PSModule organization. +4. While working with the code, do small micro commits and push on every commit. This will make it easier to review and merge your changes. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/src/docs/Modules/Repository-Defaults.md b/src/docs/Modules/Repository-Defaults.md index 7ce6b66..3575b76 100644 --- a/src/docs/Modules/Repository-Defaults.md +++ b/src/docs/Modules/Repository-Defaults.md @@ -15,6 +15,8 @@ They do not apply directly to: - Template repositories other than `Template-PSModule`. - Test, archive, service, or infrastructure repositories that are not published as module artifacts. +Two baseline expectations still apply to every PSModule repository, including the types listed above. Each repository stands on its own: it carries its own governance and community files instead of relying on the organization `.github` fallback, and each repository ships the [agent onboarding files](#agent-onboarding-files) so an agent can work in it without prior context. What differs by type is the concrete file set and layout: the required files, README shape, and framework wiring on the rest of this page are module defaults, and non-module repositories keep only the equivalent baseline appropriate to their own type. This repository, `PSModule/docs`, follows those two baseline expectations itself. + Each initiative should keep its own repository standards in its central documentation repository. For the PSModule organization, this repository is the source of truth. ## Repository creation @@ -62,10 +64,13 @@ Module repositories use the PSModule framework layout: | ---- | --------------- | | `README.md` | Concise start page for the module. | | `LICENSE` | Repository license. PSModule module repositories default to MIT unless a different license is explicitly decided. | -| `CONTRIBUTING.md` | Contribution workflow or a repository-level pointer to the organization contribution guide. | +| `CONTRIBUTING.md` | Self-contained contribution workflow for this repository. Does not rely on an organization-level fallback. | | `SECURITY.md` | Security support policy and private vulnerability reporting instructions. | | `SUPPORT.md` | Support expectations and where users ask for help. | | `CODE_OF_CONDUCT.md` | Community conduct expectations. | +| `AGENTS.md` | Agent onboarding entry point. Points agents to the canonical guidance in `PSModule/docs`. | +| `CLAUDE.md` | Claude Code entry point. Imports `AGENTS.md` so Claude reads the same instructions. | +| `.github/copilot-instructions.md` | VS Code and GitHub Copilot repository instructions. Points to the same documentation. | | `.github/PSModule.yml` | Module workflow configuration overrides. | | `.github/workflows/workflow.yml` | Reusable Process-PSModule workflow entry point. | | `.github/dependabot.yml` | Dependency and supply-chain update configuration. | @@ -102,10 +107,13 @@ Required baseline files for module repositories: | ---- | ------------------ | | `README.md` | Repository landing page and evergreen context for humans and agents. | | `LICENSE` | Clear legal terms for reuse, packaging, and redistribution. | -| `CONTRIBUTING.md` | Shared contribution workflow and expectations. | +| `CONTRIBUTING.md` | Self-contained contribution workflow and expectations for this repository. | | `SECURITY.md` | Private vulnerability reporting and latest-version support policy. | | `SUPPORT.md` | Support channel and issue-routing expectations. | | `CODE_OF_CONDUCT.md` | Community participation rules. | +| `AGENTS.md` | Cross-tool agent instructions pointing to the canonical guidance in `PSModule/docs`. | +| `CLAUDE.md` | Claude Code entry point that imports `AGENTS.md`. | +| `.github/copilot-instructions.md` | VS Code and GitHub Copilot repository instructions pointing to the documentation. | | `.github/dependabot.yml` | Supply-chain maintenance for GitHub Actions and PowerShell dependencies. | | `.github/CODEOWNERS` | Review routing for source, docs, and GitHub workflow files. | | `.github/pull_request_template.md` | Consistent PR Manager-style PR descriptions and change classification. | @@ -118,24 +126,44 @@ Required baseline files for module repositories: Repositories can add local files, but they should not remove these baseline files unless the repository is explicitly outside the module standard. +Each repository must stand on its own. It carries its own copy of every file above and does not depend on the organization `.github` fallback: that fallback is only surfaced in GitHub's web UI, and agents, linters, and local tooling do not read it. + +## Agent onboarding files + +Every repository must be usable by an agent that has never seen it before, without special configuration. Each repository carries its own agent entry points that point to the authoritative documentation instead of restating it: + +- `AGENTS.md`: the cross-tool entry point, read by the GitHub Copilot coding agent, VS Code, and other AGENTS.md-aware tools. It names what the repository is in a line or two and points to the canonical agent guidance in [`PSModule/docs`](https://github.com/PSModule/docs). +- `CLAUDE.md`: a thin file that imports `AGENTS.md` with `@AGENTS.md` so Claude Code reads the same instructions. Claude-specific notes, if any, go below the import. +- `.github/copilot-instructions.md`: repository instructions for VS Code and GitHub Copilot that point to the same documentation. + +These files are the agent equivalent of the README: pointers, not copies. Keep them short so the linked documentation stays the single source of truth. Like the other governance files, they live in the repository itself so it can stand on its own. + ## Managed file distribution -Shared files should be treated as managed files. The current distribution service is [`PSModule/Distributor`](https://github.com/PSModule/Distributor). It keeps source file sets under `Repos/{Type}/{Selection}/` and syncs those files into repositories through pull requests. +Shared repository files are managed through [`PSModule/Distributor`](https://github.com/PSModule/Distributor). Distributor is the source of truth for managed file content and file-set membership. + +Managed-file distribution follows this contract: + +- `Type` maps a repository to its file-set root (for example `Module` or `Action`). +- `SubscribeTo` declares which optional managed file sets the repository receives. +- Organization-wide mandatory file sets define non-optional governance and supply-chain files for each applicable repository type. +- Distributor delivers changes through a `managed-files/update` branch and a `⚙️ [Maintenance]: Sync managed files` pull request. +- Receiving repositories treat managed files as generated artifacts from Distributor. Local edits in the receiving repository are replaced on the next sync and must be made in Distributor instead. +- Removing a file from a file set does not implicitly delete previously synced copies; deletion is an explicit managed change. -The current Distributor model is subscription-based: +This page defines what files must exist in repositories. Distributor defines how those files are distributed and kept aligned. -- `Type` is an organization repository custom property that maps a repository to a type folder such as `Module` or `Action`. -- `SubscribeTo` is an organization repository custom property that selects file sets such as `dependabot.yml`, `Linter Settings`, `PSModule Settings`, `CODEOWNERS`, `License`, `.gitattributes`, and `.gitignore`. -- Sync changes are delivered through a `managed-files/update` branch and a `⚙️ [Maintenance]: Sync managed files` pull request. -- Managed files are overwritten by the source file set. Local edits to managed files should be made in Distributor, not directly in the receiving repository. -- Removing a file from a Distributor file set does not delete the previously distributed file from target repositories; cleanup is explicit. +### Migration for existing repositories -Two follow-up Distributor capabilities define the desired direction: +Repositories that still reflect older distribution behavior should be aligned to this contract: -- **Global file sets** should allow common file sets such as `.gitattributes`, `.gitignore`, and `License` to be defined once and made available to all repository types while still requiring subscription. -- **Mandatory file sets** should allow organization-critical files such as `SECURITY.md`, `CODE_OF_CONDUCT.md`, `CONTRIBUTING.md`, and supply-chain configuration to be pushed to applicable repositories without each repository having to subscribe manually. +1. Set or correct repository `Type` and `SubscribeTo` properties. +2. Ensure mandatory governance and supply-chain files from this standard exist in the repository. +3. Move any intended local edits in managed files into Distributor source file sets. +4. Sync from Distributor and merge the `managed-files/update` pull request. +5. Remove unmanaged duplicates or stale files explicitly when they are no longer part of an active file set. -Until mandatory file sets exist, repository owners are still responsible for ensuring the required common files exist. Distributor is the preferred implementation mechanism; this document is the standard that says what must exist and why. +After migration, the repository keeps the required files from this standard, and managed-file content changes are made through Distributor-first updates. ## Supply-chain defaults diff --git a/src/docs/Style-Guides/index.md b/src/docs/Style-Guides/index.md index c2d817d..b874da8 100644 --- a/src/docs/Style-Guides/index.md +++ b/src/docs/Style-Guides/index.md @@ -5,7 +5,7 @@ description: Coding style guidelines for PSModule repositories. # Style Guides (Moved) -Style-guide content is now canonical in MSXOrg/docs. +Style guide content is now canonical in MSXOrg/docs. Use: diff --git a/src/overrides/assets/javascripts/abbreviation-preview.js b/src/overrides/assets/javascripts/abbreviation-preview.js deleted file mode 100644 index e397ba0..0000000 --- a/src/overrides/assets/javascripts/abbreviation-preview.js +++ /dev/null @@ -1,94 +0,0 @@ -/* global document$ */ -(function () { - "use strict"; - - // Map abbreviations to glossary pages. Add entries as glossary coverage expands. - var ABBR_TO_PAGE = { - API: "Dictionary/api/", - "CI/CD": "Dictionary/ci-cd/", - CI: "Dictionary/ci-cd/", - CD: "Dictionary/ci-cd/", - GH: "Dictionary/github/", - GitHub: "Dictionary/github/", - Git: "Dictionary/git/", - LTS: "Dictionary/lts/", - MkDocs: "Dictionary/mkdocs/", - REST: "Dictionary/rest-api/", - "REST API": "Dictionary/rest-api/", - YAML: "Dictionary/yaml/" - }; - - function titleCase(value) { - return value - .toLowerCase() - .split(/\s+/) - .filter(Boolean) - .map(function (part) { - return part.charAt(0).toUpperCase() + part.slice(1); - }) - .join(" "); - } - - function getAbbreviationText(node) { - return (node.textContent || "").trim(); - } - - function toAbsoluteHref(path) { - var scopeBase = "/"; - if (typeof window !== "undefined" && window.__md_scope && window.__md_scope.base) { - scopeBase = window.__md_scope.base; - } - - if (!scopeBase.endsWith("/")) { - scopeBase += "/"; - } - - return scopeBase + path; - } - - function upgradeAbbreviation(node) { - if (!node || node.dataset.abbrLinked === "true") { - return; - } - - var key = getAbbreviationText(node); - var target = ABBR_TO_PAGE[key]; - if (!target) { - return; - } - - var link = document.createElement("a"); - link.href = toAbsoluteHref(target); - link.className = "abbr-preview-link"; - link.innerHTML = node.innerHTML; - - // Keep native tooltip text as fallback while enabling preview-on-hover for links. - if (node.hasAttribute("title")) { - link.setAttribute("title", node.getAttribute("title")); - } else { - link.setAttribute("title", titleCase(key)); - } - - // Mark transformed to avoid repeated wrapping on instant navigation reloads. - link.dataset.abbrLinked = "true"; - node.replaceWith(link); - } - - function enhanceAbbreviations() { - var nodes = document.querySelectorAll("abbr"); - nodes.forEach(upgradeAbbreviation); - } - - if (typeof document$ !== "undefined" && document$.subscribe) { - document$.subscribe(function () { - enhanceAbbreviations(); - }); - return; - } - - if (document.readyState === "loading") { - document.addEventListener("DOMContentLoaded", enhanceAbbreviations); - } else { - enhanceAbbreviations(); - } -})();