From a48c598b2e2497ac45c959ebccee12515f6a9258 Mon Sep 17 00:00:00 2001 From: Callahan Kovacs Date: Tue, 21 Apr 2026 15:29:39 -0500 Subject: [PATCH 1/2] ci: setup copilot-collections Signed-off-by: Callahan Kovacs --- .github/.copilot-collections.yaml | 7 +++++++ .github/workflows/copilot-collections-update.yaml | 11 +++++++++++ .pre-commit-config.yaml | 2 ++ Makefile | 4 ++++ 4 files changed, 24 insertions(+) create mode 100644 .github/.copilot-collections.yaml create mode 100644 .github/workflows/copilot-collections-update.yaml diff --git a/.github/.copilot-collections.yaml b/.github/.copilot-collections.yaml new file mode 100644 index 00000000..887b507f --- /dev/null +++ b/.github/.copilot-collections.yaml @@ -0,0 +1,7 @@ +# https://github.com/canonical/copilot-collections + +copilot: + version: v0.12.0 + collections: + - starcraft-core + - starcraft-docs diff --git a/.github/workflows/copilot-collections-update.yaml b/.github/workflows/copilot-collections-update.yaml new file mode 100644 index 00000000..df28b1af --- /dev/null +++ b/.github/workflows/copilot-collections-update.yaml @@ -0,0 +1,11 @@ +name: Update Copilot Instructions +on: + schedule: + - cron: "0 9 * * 1" # Run every Monday at 09:00 UTC + workflow_dispatch: + +jobs: + check-update: + # Pinned to @main to get the latest logic, but the content version is controlled by .github/.copilot-collections.yaml + uses: canonical/copilot-collections/.github/workflows/auto_update_collections.yaml@main + secrets: inherit diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 04cff15f..7993c31e 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,5 +1,7 @@ # See https://pre-commit.com for more information # See https://pre-commit.com/hooks.html for more hooks +# skills and instructions are automatically generated +exclude: ^\.github/(skills|instructions)/ repos: - repo: https://github.com/pre-commit/pre-commit-hooks rev: "v6.0.0" diff --git a/Makefile b/Makefile index c389b06c..24eca94e 100644 --- a/Makefile +++ b/Makefile @@ -20,6 +20,10 @@ endif include common.mk +# Instructions and skills are imported from canonical/copilot-collections. +# This extends PRETTIER_FILES from common.mk. +PRETTIER_FILES += !.github/instructions/** !.github/skills/** + .PHONY: format format: format-ruff format-codespell format-prettier format-pre-commit ## Run all automatic formatters From 7eef3e2d47e0e41902696c4e65646267e0b68c86 Mon Sep 17 00:00:00 2001 From: Callahan Kovacs Date: Tue, 21 Apr 2026 15:33:13 -0500 Subject: [PATCH 2/2] ci: initial sync with canonical/copilot-collections Signed-off-by: Callahan Kovacs --- .../core-directive.instructions.md | 40 ++ .../documentation-rtd.instructions.md | 94 +++ .../documentation.instructions.md | 116 ++++ .../instructions/instructions.instructions.md | 256 +++++++ .../python-code-commenting.instructions.md | 165 +++++ .../starcraft-docs-meta.instructions.md | 80 +++ .../starcraft-docs-style.instructions.md | 505 ++++++++++++++ .github/skills/documentation-build/SKILL.md | 96 +++ .../skills/documentation-diataxis/SKILL.md | 152 +++++ .github/skills/documentation-review/SKILL.md | 198 ++++++ .../references/doc-review-report-template.md | 68 ++ .../skills/documentation-structure/SKILL.md | 79 +++ .github/skills/documentation-style/SKILL.md | 74 ++ .../references/doc-style-guide.md | 643 ++++++++++++++++++ .github/skills/documentation-verify/SKILL.md | 80 +++ .../references/report_format.md | 144 ++++ .../references/verification_procedures.md | 178 +++++ 17 files changed, 2968 insertions(+) create mode 100644 .github/instructions/core-directive.instructions.md create mode 100644 .github/instructions/documentation-rtd.instructions.md create mode 100644 .github/instructions/documentation.instructions.md create mode 100644 .github/instructions/instructions.instructions.md create mode 100644 .github/instructions/python-code-commenting.instructions.md create mode 100644 .github/instructions/starcraft-docs-meta.instructions.md create mode 100644 .github/instructions/starcraft-docs-style.instructions.md create mode 100644 .github/skills/documentation-build/SKILL.md create mode 100644 .github/skills/documentation-diataxis/SKILL.md create mode 100644 .github/skills/documentation-review/SKILL.md create mode 100644 .github/skills/documentation-review/references/doc-review-report-template.md create mode 100644 .github/skills/documentation-structure/SKILL.md create mode 100644 .github/skills/documentation-style/SKILL.md create mode 100644 .github/skills/documentation-style/references/doc-style-guide.md create mode 100644 .github/skills/documentation-verify/SKILL.md create mode 100644 .github/skills/documentation-verify/references/report_format.md create mode 100644 .github/skills/documentation-verify/references/verification_procedures.md diff --git a/.github/instructions/core-directive.instructions.md b/.github/instructions/core-directive.instructions.md new file mode 100644 index 00000000..82847ac1 --- /dev/null +++ b/.github/instructions/core-directive.instructions.md @@ -0,0 +1,40 @@ +--- +applyTo: '**' +description: 'Prevent Copilot from wreaking havoc across your codebase, keeping it under control.' +--- + +## Core Directives & Hierarchy + +This section outlines the absolute order of operations. These rules have the highest priority and must not be violated. + +1. **Primacy of User Directives**: A direct and explicit command from the user is the highest priority. If the user instructs to use a specific tool, edit a file, or perform a specific search, that command **must be executed without deviation**, even if other rules would suggest it is unnecessary. All other instructions are subordinate to a direct user order. +2. **Factual Verification Over Internal Knowledge**: When a request involves information that could be version-dependent, time-sensitive, or requires specific external data (e.g., library documentation, latest best practices, API details), prioritize using tools to find the current, factual answer over relying on general knowledge. +3. **Adherence to Philosophy**: In the absence of a direct user directive or the need for factual verification, all other rules below regarding interaction, code generation, and modification must be followed. + +## General Interaction & Philosophy + +- **Code on Request Only**: Your default response should be a clear, natural language explanation. Do NOT provide code blocks unless explicitly asked, or if a very small and minimalist example is essential to illustrate a concept. Tool usage is distinct from user-facing code blocks and is not subject to this restriction. +- **Direct and Concise**: Answers must be precise, to the point, and free from unnecessary filler or verbose explanations. Get straight to the solution without "beating around the bush". +- **Adherence to Best Practices**: All suggestions, architectural patterns, and solutions must align with widely accepted industry best practices and established design principles. Avoid experimental, obscure, or overly "creative" approaches. Stick to what is proven and reliable. +- **Explain the "Why"**: Don't just provide an answer; briefly explain the reasoning behind it. Why is this the standard approach? What specific problem does this pattern solve? This context is more valuable than the solution itself. + +## Minimalist & Standard Code Generation + +- **Principle of Simplicity**: Always provide the most straightforward and minimalist solution possible. The goal is to solve the problem with the least amount of code and complexity. Avoid premature optimization or over-engineering. +- **Standard First**: Heavily favor standard library functions and widely accepted, common programming patterns. Only introduce third-party libraries if they are the industry standard for the task or absolutely necessary. +- **Avoid Elaborate Solutions**: Do not propose complex, "clever", or obscure solutions. Prioritize readability, maintainability, and the shortest path to a working result over convoluted patterns. +- **Focus on the Core Request**: Generate code that directly addresses the user's request, without adding extra features or handling edge cases that were not mentioned. + +## Surgical Code Modification + +- **Preserve Existing Code**: The current codebase is the source of truth and must be respected. Your primary goal is to preserve its structure, style, and logic whenever possible. +- **Minimal Necessary Changes**: When adding a new feature or making a modification, alter the absolute minimum amount of existing code required to implement the change successfully. +- **Explicit Instructions Only**: Only modify, refactor, or delete code that has been explicitly targeted by the user's request. Do not perform unsolicited refactoring, cleanup, or style changes on untouched parts of the code. +- **Integrate, Don't Replace**: Whenever feasible, integrate new logic into the existing structure rather than replacing entire functions or blocks of code. + +## Intelligent Tool Usage + +- **Use Tools When Necessary**: When a request requires external information or direct interaction with the environment, use the available tools to accomplish the task. Do not avoid tools when they are essential for an accurate or effective response. +- **Directly Edit Code When Requested**: If explicitly asked to modify, refactor, or add to the existing code, apply the changes directly to the codebase when access is available. Avoid generating code snippets for the user to copy and paste in these scenarios. The default should be direct, surgical modification as instructed. +- **Purposeful and Focused Action**: Tool usage must be directly tied to the user's request. Do not perform unrelated searches or modifications. Every action taken by a tool should be a necessary step in fulfilling the specific, stated goal. +- **Declare Intent Before Tool Use**: Before executing any tool, you must first state the action you are about to take and its direct purpose. This statement must be concise and immediately precede the tool call. diff --git a/.github/instructions/documentation-rtd.instructions.md b/.github/instructions/documentation-rtd.instructions.md new file mode 100644 index 00000000..323657b3 --- /dev/null +++ b/.github/instructions/documentation-rtd.instructions.md @@ -0,0 +1,94 @@ +--- +description: 'Guidelines for documentation-related suggestions.' +applyTo: 'docs/**/*.md, docs/**/*.rst' +--- + +# Documentation instructions for Read the Docs projects + +## Purpose + +This file provides specific guidance for testing and reviewing documentation in Read the Docs projects. + +## Tests & CI + +The CI expects documentation to pass `spelling`, `linkcheck`, `lint-md`, and `vale`; address reported issues rather than silencing the tools. + +### Linting & checks (how to run) + +Run the docs linters via the docs-level Makefile targets: + +* `make spelling`: Runs the spelling checks. +* `make linkcheck`: Runs the link checker. +* `make lint-md`: Runs the Markdown linter. +* `make vale`: Runs the style checker. + +## Admonitions + +Admonition directives are a standardized way of communicating different types of information. They should be used for tips, notes, warnings, and important information that the reader should not skip over or miss. + +For `*.md` files, admonitions are formatted in the following way: + +```` +```{note} +A note. +``` +```` + +For `*.rst` files, admonitions are formatted in this way: + +``` +.. note:: + + A note. +``` + +Adhere to the following conventions: + +- Use admonitions sparingly in the documentation. Offer suggestions to remove admonitions when they are not necessary (for example, if the text is not necessary for the user to read). +- Only use the following types: `note`, `tip`, `warning`, `important` + +## Internal references + +When adding a reference to a document in the RTD project, use a target contained in the document. +The document's target should be defined at the top of the document. + +The target is defined like this for `*.md` files: + +``` +(target_ID)= + +# Title of document +``` + +To reference a target in a `*md` file, use the following syntax: + +``` +{ref}`Link text ` +``` + +In `*.rst` files, the targets are defined like this: + +``` +.. _target_ID: + +Title of document +================= +``` + +To reference a target in a `*.rst` file, use the following syntax: + +``` +:ref:`Link text ` +``` + +Adhere to the following conventions: + +- Never use paths when referencing another document. Always use targets. If there is no existing target, add one. +- If you want to reference a specific section within a document, add the target directly above the relevant section and use that target when creating the reference. + +## Small-edit rules for AI agents + +- Do not change `docs/index.md` structure without updating the `toctree` directive — keep the order and paths in sync with files under `docs/`. +- When adding a new page in one of the folders of `docs`, add a short entry in the landing page if there's a landing page in the folder (e.g., if adding a new how-to guide, update the landing page `docs/how-to/landing-page.md`). +- When adding new page, update the `toctree` directive in the relevant index page (`docs/index.md` for a top-level page, and `docs/*/index.md` for a new page in a specific folder). +- When moving or removing a page, you MUST add a redirect in `docs/conf.py` to prevent broken links and CI errors. Update the `redirects` dictionary mapping the old path (relative to `docs/` and without extension) to the new path. diff --git a/.github/instructions/documentation.instructions.md b/.github/instructions/documentation.instructions.md new file mode 100644 index 00000000..bf8a9b01 --- /dev/null +++ b/.github/instructions/documentation.instructions.md @@ -0,0 +1,116 @@ +--- +description: 'Core guidelines for documentation-related suggestions.' +applyTo: 'docs/**/*.md' +--- + +# Documentation instructions for GitHub Copilot + +## Purpose + +This file provides general guidance for reviewing documentation. + +## Core Directives + +This section outlines the absolute order of operations. These rules have the highest priority and must not be violated. + +1. **Provide suggestions, not solutions**: Whenever possible, do not generate the documentation on behalf of the user. Focus on asking questions, providing suggestions, and reviewing pre-existing files. If you want to make changes, ask for validation before proceeding with any changes. +2. **Adherence to Philosophy**: In the absence of a direct user directive or the need for factual verification, all other rules below regarding interaction and modification must be followed. + +## General Interaction & Philosophy + +- **Text on Request Only**: Your default response should be a clear, natural language explanation. Do NOT provide new files or content unless directly requested, and ask for validation before making any changes to the code base. +- **Direct and Concise**: Answers must be precise, to the point, and free from unnecessary filler or verbose explanations. Get straight to the solution without "beating around the bush". +- **Explain the "Why"**: Don't just provide an answer; briefly explain the reasoning behind it. Why is this suggestion clearer, more concise, or easier to understand? + +## General Structure + +In this repository, the documentation is placed in a dedicated `docs` directory. The purpose of the files in this directory is to provide information, instructions, and conceptual understanding of the code for users. + +The top-level `docs` directory should contain an overview or home page called `index.md`. This file should provide a brief description of the project, what needs it serves, and who the primary user base is. + +The rest of the documentation follows the Diataxis framework consisting of four categories of documentation: + +1. **Tutorials**: A practice lesson that walks a user through a learning experience. Tutorials should be placed in the `docs/tutorial` directory, but sometimes they're placed in the top-level `docs` directory. +2. **How-to guides**: Addresses real-world goals or problems by providing practical directions. How-to guides should be placed in the `docs/how-to` directory. +3. **Reference**: Contains technical descriptions of theoretical knowledge. Reference documents should be placed in the `docs/reference` directory. +4. **Explanation**: Provides context and background on topics for the user to understand the bigger picture. Explanation documents should be placed in the `docs/explanation` directory. + +All files should neatly fit into one of these four categories. Do NOT mix content between multiple categories into a single document. Instead, suggest splitting up content into multiple documents to preserve the structure and Diataxis framework. + +### Guidance on tutorials + +A tutorial is a learning-based, end-to-end experience that provides a complete learning journey for the user. The majority of our tutorials walk the user through a basic deployment of the charm in the repository. + +The tutorial should contain the following pieces: + +- **A title**. This title should be more descriptive than "Getting started" + or "Quick guide" which are both indicative of a how-to guide. In a single + statement, what will the user accomplish in the tutorial? +- **An introduction**. In a couple of sentences, introduce the charm and + what the tutorial aims to do. Avoid using a statement like "you will learn", + as that makes an assumption about the user's prior knowledge. Focus + instead on what the user will do or accomplish. +- **What you'll do**. This should be the first section in the tutorial. It + aims to quickly and succinctly establish everything the user will do in the + tutorial. +- **What you'll need**. This section should contain a list of resources, software + or other tools that the user will need before starting the tutorial. In this section, + provide information on the supported architecture(s) like AMD64 or ARM64. + Also include additional information if the + tutorial will require significant resources (CPU, RAM, or disk space). You can + also suggest a Multipass VM to create an isolated testing environment for the tutorial. +- **Set up tutorial model**. The tutorial should begin at this point. Have + the user create Juju model with a predetermined name so that you can reference + the model name throughout the tutorial. +- **Deploy the charm + its dependencies**. If the charm requires any other + charms to successfully deploy, either include in a single section or split into + multiple sections. Use this part of the tutorial to enable any required configurations. + Make sure to briefly explain what the configurations or additional charms are + and why the steps are necessary. Split up important commands into separate + command blocks, and provide explanations between each command. +- **Check the deployment was successful**. Instruct the user to run + ``juju status`` and show example output. If appropriate, also instruct the + user to run ``kubectl get pods -n `` and show the output. + Offer a brief explanation so that the user knows that the deployment was + successful. +- **Some final checkpoint**. Have the user visit a website, change a + configuration, or run an action (maybe some combination of the three). Check + that this step worked; this is more obvious for a website, but you may need + to be creative if you have the user change a configuration or run an action. +- **Tear down the environment**. This should be the final section. Take a moment + to congratulate the user for getting through the tutorial! Have the user + destroy the Juju model that they set up, and if applicable, instruct them to + delete the Multipass VM. + +### Guidance on how-to guides + +- How-to guides should contain a title with the format `# How to...`. The title should +concisely summarize the real-world problem addressed by the document. +- How-to guides should contain at least one CLI command that user can run to address the +problem or achieve the goal. +- Provide instructions or tasks that the user can take to achieve the goal. Avoid gerunds. + + +## Style guide pointers + +- **Spelling**: Use US English for spelling suggestions. +- **Headings**: Use sentence case for headings. Avoid punctuation in headings. Do not skip levels in heading hierarchy. Do not use consecutive headings without intervening text, and suggest removing headings that don't enhance the understanding. Don't overuse `code` styling in headings. +- **Code examples**: Do not use prompt marks (for example, `$` or `#`) in code examples. Do not use comments in code examples; instead, put any comments directly into the text. Whenever possible, split up multiple commands into separate code blocks and provide explanations in between the code blocks. Use Git-flavoured Markdown with fenced code blocks (```) and command examples as shell blocks. +- **Lists**: Only use numbered lists when there is an inherent order to the items. +- **Latin words and phrases**: We can't assume the reader is familiar with Latin words and phrases. Words such as "etc.", "i.e.", "e.g.", "per", "versus", and "via" should be avoided. + +## Small-edit rules for AI agents + +- Avoid describing tasks as "easy" or "simple". +- Preserve existing link targets and code samples formatting. If you change any heading filename or path, update all relative links in `docs/` accordingly. +- Demonstrative pronouns ("this", "these", "those", and "that") should be accompanied by the target noun when there's a risk of ambiguity in the paragraph. An isolated demonstrative pronoun can be used if there's no chance of ambiguity. In cases where a paragraph describes multiple ideas, avoid isolated demonstrative pronouns and be as specific as possible. + +## Changelog guidance + +If you modify a procedure (commands, required versions, prerequisites) and a `docs/changelog.md` exists, add a short note in `docs/changelog.md` summarizing the user-facing change. + +If you add a new file into `docs`, add a short note in `docs/changelog.md` summarizing the user-facing change. + +If there are no user-relevant changes, then the changelog does not need to be updated. + + diff --git a/.github/instructions/instructions.instructions.md b/.github/instructions/instructions.instructions.md new file mode 100644 index 00000000..c53da844 --- /dev/null +++ b/.github/instructions/instructions.instructions.md @@ -0,0 +1,256 @@ +--- +description: 'Guidelines for creating high-quality custom instruction files for GitHub Copilot' +applyTo: '**/*.instructions.md' +--- + +# Custom Instructions File Guidelines + +Instructions for creating effective and maintainable custom instruction files that guide GitHub Copilot in generating domain-specific code and following project conventions. + +## Project Context + +- Target audience: Developers and GitHub Copilot working with domain-specific code +- File format: Markdown with YAML frontmatter +- File naming convention: lowercase with hyphens (e.g., `react-best-practices.instructions.md`) +- Location: `.github/instructions/` directory +- Purpose: Provide context-aware guidance for code generation, review, and documentation + +## Required Frontmatter + +Every instruction file must include YAML frontmatter with the following fields: + +```yaml +--- +description: 'Brief description of the instruction purpose and scope' +applyTo: 'glob pattern for target files (e.g., **/*.ts, **/*.py)' +--- +``` + +### Frontmatter Guidelines + +- **description**: Single-quoted string, 1-500 characters, clearly stating the purpose +- **applyTo**: Glob pattern(s) specifying which files these instructions apply to + - Single pattern: `'**/*.ts'` + - Multiple patterns: `'**/*.ts, **/*.tsx, **/*.js'` + - Specific files: `'src/**/*.py'` + - All files: `'**'` + +## File Structure + +A well-structured instruction file should include the following sections: + +### 1. Title and Overview + +- Clear, descriptive title using `#` heading +- Brief introduction explaining the purpose and scope +- Optional: Project context section with key technologies and versions + +### 2. Core Sections + +Organize content into logical sections based on the domain: + +- **General Instructions**: High-level guidelines and principles +- **Best Practices**: Recommended patterns and approaches +- **Code Standards**: Naming conventions, formatting, style rules +- **Architecture/Structure**: Project organization and design patterns +- **Common Patterns**: Frequently used implementations +- **Security**: Security considerations (if applicable) +- **Performance**: Optimization guidelines (if applicable) +- **Testing**: Testing standards and approaches (if applicable) + +### 3. Examples and Code Snippets + +Provide concrete examples with clear labels: + +```markdown +### Good Example +\`\`\`language +// Recommended approach +code example here +\`\`\` + +### Bad Example +\`\`\`language +// Avoid this pattern +code example here +\`\`\` +``` + +### 4. Validation and Verification (Optional but Recommended) + +- Build commands to verify code +- Linting and formatting tools +- Testing requirements +- Verification steps + +## Content Guidelines + +### Writing Style + +- Use clear, concise language +- Write in imperative mood ("Use", "Implement", "Avoid") +- Be specific and actionable +- Avoid ambiguous terms like "should", "might", "possibly" +- Use bullet points and lists for readability +- Keep sections focused and scannable + +### Best Practices + +- **Be Specific**: Provide concrete examples rather than abstract concepts +- **Show Why**: Explain the reasoning behind recommendations when it adds value +- **Use Tables**: For comparing options, listing rules, or showing patterns +- **Include Examples**: Real code snippets are more effective than descriptions +- **Stay Current**: Reference current versions and best practices +- **Link Resources**: Include official documentation and authoritative sources + +### Common Patterns to Include + +1. **Naming Conventions**: How to name variables, functions, classes, files +2. **Code Organization**: File structure, module organization, import order +3. **Error Handling**: Preferred error handling patterns +4. **Dependencies**: How to manage and document dependencies +5. **Comments and Documentation**: When and how to document code +6. **Version Information**: Target language/framework versions + +## Patterns to Follow + +### Bullet Points and Lists + +```markdown +## Security Best Practices + +- Always validate user input before processing +- Use parameterized queries to prevent SQL injection +- Store secrets in environment variables, never in code +- Implement proper authentication and authorization +- Enable HTTPS for all production endpoints +``` + +### Tables for Structured Information + +```markdown +## Common Issues + +| Issue | Solution | Example | +| ---------------- | ------------------- | ----------------------------- | +| Magic numbers | Use named constants | `const MAX_RETRIES = 3` | +| Deep nesting | Extract functions | Refactor nested if statements | +| Hardcoded values | Use configuration | Store API URLs in config | +``` + +### Code Comparison + +```markdown +### Good Example - Using TypeScript interfaces +\`\`\`typescript +interface User { + id: string; + name: string; + email: string; +} + +function getUser(id: string): User { + // Implementation +} +\`\`\` + +### Bad Example - Using any type +\`\`\`typescript +function getUser(id: any): any { + // Loses type safety +} +\`\`\` +``` + +### Conditional Guidance + +```markdown +## Framework Selection + +- **For small projects**: Use Minimal API approach +- **For large projects**: Use controller-based architecture with clear separation +- **For microservices**: Consider domain-driven design patterns +``` + +## Patterns to Avoid + +- **Overly verbose explanations**: Keep it concise and scannable +- **Outdated information**: Always reference current versions and practices +- **Ambiguous guidelines**: Be specific about what to do or avoid +- **Missing examples**: Abstract rules without concrete code examples +- **Contradictory advice**: Ensure consistency throughout the file +- **Copy-paste from documentation**: Add value by distilling and contextualizing + +## Testing Your Instructions + +Before finalizing instruction files: + +1. **Test with Copilot**: Try the instructions with actual prompts in VS Code +2. **Verify Examples**: Ensure code examples are correct and run without errors +3. **Check Glob Patterns**: Confirm `applyTo` patterns match intended files + +## Example Structure + +Here's a minimal example structure for a new instruction file: + +```markdown +--- +description: 'Brief description of purpose' +applyTo: '**/*.ext' +--- + +# Technology Name Development + +Brief introduction and context. + +## General Instructions + +- High-level guideline 1 +- High-level guideline 2 + +## Best Practices + +- Specific practice 1 +- Specific practice 2 + +## Code Standards + +### Naming Conventions +- Rule 1 +- Rule 2 + +### File Organization +- Structure 1 +- Structure 2 + +## Common Patterns + +### Pattern 1 +Description and example + +\`\`\`language +code example +\`\`\` + +### Pattern 2 +Description and example + +## Validation + +- Build command: `command to verify` +- Linting: `command to lint` +- Testing: `command to test` +``` + +## Maintenance + +- Review instructions when dependencies or frameworks are updated +- Update examples to reflect current best practices +- Remove outdated patterns or deprecated features +- Add new patterns as they emerge in the community +- Keep glob patterns accurate as project structure evolves + +## Additional Resources + +- [Custom Instructions Documentation](https://code.visualstudio.com/docs/copilot/customization/custom-instructions) +- [Awesome Copilot Instructions](https://github.com/github/awesome-copilot/tree/main/instructions) diff --git a/.github/instructions/python-code-commenting.instructions.md b/.github/instructions/python-code-commenting.instructions.md new file mode 100644 index 00000000..86199f30 --- /dev/null +++ b/.github/instructions/python-code-commenting.instructions.md @@ -0,0 +1,165 @@ +--- +description: 'Guidelines for GitHub Copilot to write comments to achieve self-explanatory code with fewer comments. Examples are in Python but it should work on any language that has comments.' +applyTo: '**' +--- + +# Self-explanatory Code Commenting Instructions + +## Core Principle +**Write code that speaks for itself. Comment only when necessary to explain WHY, not WHAT.** +We do not need comments most of the time. + +## Commenting Guidelines + +### ❌ AVOID These Comment Types + +**Obvious Comments** +```python +# Bad: States the obvious +counter = 0 # Initialize counter to zero +counter += 1 # Increment counter by one +``` + +**Redundant Comments** +```python +# Bad: Comment repeats the code +def get_user_name(): + return user.name # Return the user's name +``` + +**Outdated Comments** +```python +# Bad: Comment doesn't match the code +# Calculate tax at 5% rate +tax = price * 0.08 # Actually 8% +``` + +### ✅ WRITE These Comment Types + +**Complex Business Logic** +```python +# Good: Explains WHY this specific calculation +# Apply progressive tax brackets: 10% up to 10k, 20% above +tax = calculate_progressive_tax(income, [0.10, 0.20], [10_000]) +``` + +**Non-obvious Algorithms** +```python +# Good: Explains the algorithm choice +# Using Floyd–Warshall for all-pairs shortest paths +# because we need distances between all nodes +for k in range(vertices): + for i in range(vertices): + for j in range(vertices): + # ... implementation + pass +``` + +**Regex Patterns** +```python +# Good: Explains what the regex matches +# Match email format: username@domain.extension +import re +email_pattern = re.compile(r'^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$') +``` + +**API Constraints or Gotchas** +```python +# Good: Explains external constraint +# GitHub API rate limit: 5000 requests/hour for authenticated users +await rate_limiter.wait() +response = await http_client.get(github_api_url) +``` + +## Decision Framework + +Before writing a comment, ask: +1. **Is the code self-explanatory?** → No comment needed +2. **Would a better variable/function name eliminate the need?** → Refactor instead +3. **Does this explain WHY, not WHAT?** → Good comment +4. **Will this help future maintainers?** → Good comment + +## Special Cases for Comments + +### Public APIs +```python +def calculate_compound_interest(principal: float, rate: float, time: float, compound_frequency: int = 1) -> float: + """ + Calculate compound interest using the standard formula. + + Args: + principal (float): Initial amount invested. + rate (float): Annual interest rate (as decimal, e.g., 0.05 for 5%). + time (float): Time period in years. + compound_frequency (int, optional): How many times per year interest compounds (default: 1). + + Returns: + float: Final amount after compound interest. + """ + # ... implementation + pass +``` + +### Configuration and Constants +```python +# Good: Explains the source or reasoning +MAX_RETRIES = 3 # Based on network reliability studies +API_TIMEOUT = 5.0 # AWS Lambda timeout is 15s, leaving buffer (seconds) +``` + +### Annotations +```python +# TODO: Replace with proper user authentication after security review +# FIXME: Memory leak in production - investigate connection pooling +# HACK: Workaround for bug in library v2.1.0 - remove after upgrade +# NOTE: This implementation assumes UTC timezone for all calculations +# WARNING: This function mutates the input list instead of returning a copy +# PERF: Consider caching this result if called frequently in a hot path +# SECURITY: Validate input to prevent SQL injection before using in query +# BUG: Edge case failure when list is empty - needs investigation +# REFACTOR: Extract this logic into separate utility function for reusability +# DEPRECATED: Use new_api_function() instead - this will be removed in v3.0 +``` + +## Anti-Patterns to Avoid + +### Dead Code Comments +```python +# Bad: Don't comment out code +# def old_function(): +# ... +def new_function(): + ... +``` + +### Changelog Comments +```python +# Bad: Don't maintain history in comments +# Modified by John on 2023-01-15 +# Fixed bug reported by Sarah on 2023-02-03 +def process_data(): + # ... implementation + pass +``` + +### Divider Comments +```python +# Bad: Don't use decorative comments +# ===================================== +# UTILITY FUNCTIONS +# ===================================== +``` + +## Quality Checklist + +Before committing, ensure your comments: +- [ ] Explain WHY, not WHAT +- [ ] Are grammatically correct and clear +- [ ] Will remain accurate as code evolves +- [ ] Add genuine value to code understanding +- [ ] Are placed appropriately (above the code they describe) +- [ ] Use proper spelling and professional language + +## Summary + +Remember: **The best comment is the one you don't need to write because the code is self-documenting.** diff --git a/.github/instructions/starcraft-docs-meta.instructions.md b/.github/instructions/starcraft-docs-meta.instructions.md new file mode 100644 index 00000000..9edf7c32 --- /dev/null +++ b/.github/instructions/starcraft-docs-meta.instructions.md @@ -0,0 +1,80 @@ +--- +applyTo: 'docs/**/*.rst, docs/**/*.md' +--- + + + +# Add a page meta description + +Search engines present options for the user to consider. Each search result contains at minimum the page's title, snippet, and icon. From these elements, the user chooses what pages to visit. + +A *meta description* is a short summary that search engines often reuse for the search result's snippet. Since the meta description helps the user decide in advance whether a page contains what they seek, it has a direct impact on whether the user visits our documentation. Therefore, **all new pages in a product's documentation must include a meta description.** + +## Format a meta description + +At the top of a page, add this structure: + +``` rst +.. meta:: + :description: +``` + +The meta description must be one line, because Sphinx options don't support line breaks. + +## Write a meta description + +**Do** write the meta description *after* the page is written. The meta description is a reflection of what's actually on the page. + +**Do** reuse text from the page itself when it's convenient. + +**Do** share descriptions between documents with the same formats. For example, use the same meta description for every page of release notes, but replace the version number. + +**Do** frame sentences in terms of *actions* and *facts*. + + + + + + + + + + + + + + + + + + +
TypeStarts with phrases like...

Action

Get started with

+

Learn about

+

Find information about

Fact

The encabulator is a circuit that

+

The Chef init profile sets up a basic project file for

+

Starcraft is compatible with

+ +**Do** put key terms near the start. + +**Do** aim for an average of 140 characters. Cut any detail about the topic that isn't essential to helping the user make a decision. + +**Don't** exceed 160 characters. Search engines will cut the snippet short. + +**Don't** write to market, motivate, or compel. Marketing prose with rhetoric like the following isn't appropriate for documentation. + +> Don't just write code; deliver a product. Start your journey today and turn your project into a production-ready snap. + +**Don't** include qualities or claims like *simple*, *easy*, or *best-in-class*. + +**Don't** include key terms that aren't on the page. + +**Don't** use pronouns such as *you*, *your*, *we*, or *our*. These waste space and don't match the tone of a description. + +## Example + +This is an example of a good meta description for *Set up Starcraft*. + +``` rst +.. meta:: + :description: Learn how to install Starcraft on a local system. Starcraft is available as a snap on all GNU/Linux systems that support systemd. +``` diff --git a/.github/instructions/starcraft-docs-style.instructions.md b/.github/instructions/starcraft-docs-style.instructions.md new file mode 100644 index 00000000..edc9a5b9 --- /dev/null +++ b/.github/instructions/starcraft-docs-style.instructions.md @@ -0,0 +1,505 @@ +--- +applyTo: 'docs/**/*.rst, docs/**/*.md' +--- + + + +# Starcraft style guide + +This is the style guide for user and developer documentation in the craft apps and libraries. It's a supplement to the [Canonical Documentation Style Guide](https://docs.ubuntu.com/styleguide). + +## Tone + +Starcraft is for developers, which means Starcraft is for humans. In our tone we must never forget we're speaking directly to the person behind the device. + +Here are fundamentals for the persona we adopt when speaking to the user. They're the foundation for our style: + +- We write, primarily, as teachers and guides. We provide for the user's understanding, and guide their work. +- We are the team behind the Starcraft products. We take responsibility for them. +- Let that which is exciting, inspiring, and interesting come across on the page. If technology has this effect on you, allow it to come out in your writing. +- Documentation is one side of an ongoing dialogue with the user. Dialogue is conversation, so write directly and straightforwardly, in plain language. Write like the user will respond to you directly -- they often do. +- Be brief. The user's time and attention is a gift they don't hand out lightly. Be responsible with it. Don't squander it. +- In the course of events, identify the person in the loop. Humans come to decisions, have opinions, and make mistakes. Processes, systems, and machines don't. +- Many ideas in computing are abstract, metaphorical, and even at times whimsical. If it helps the user understand, use analogy and metaphor. Grounding an idea in a familiar concept is an effective technique for communicating abstract and complex ideas. +- When something is difficult, acknowledge the pain it causes. +- When something is uncertain, be forthcoming about why. + +## Inclusivity + +### Singular *they* and *them* + +Don't presume a gender when referring to a nominal or anonymous person: + +> Once he installs the app +> +> Wait for the user to make her choice + +Do use singular third-person pronouns: + +> Once they install the app +> +> Wait for the user to make their choice + +### Names for people + +Don't use gendered names in examples or placeholders: + +> Alice +> +> Bob +> +> Carol +> +> David + +Do use unisex names: + +> Alex +> +> Blair +> +> Cam +> +> Devin + +## Accessibility + +### Image alt text + +All images must have alt text. The [W3C Images Tutorial](https://www.w3.org/WAI/tutorials/images/) provides complete guidance for how to write one. + +### Relative positioning + +Don't refer to relative positions and directions: + +> The above example +> +> The code below +> +> The **Render** node at the bottom-right of the chart + +Do refer to chronological sequence, linear sequence, or the item itself: + +> The previous example +> +> The following code +> +> The **Render** node + +The user is able to locate elements in space in multiple senses. Relative positions in a document, a graphic, or an interface are likely to change, therefore documenting them precisely increases maintenance debt. They also aren't helpful when the page is recited by a screen reader. + +## Names + +### Product names + +Don't modify the product names, even if it's grammatical: + +> Starcraft's +> +> Starcrafts +> +> Starcrafty + +Do keep product names discrete and unaltered: + +> Starcraft + +### Version names + +Don't use special formatting for version names: + +> Starcraft `9` +> +> Starcraft v9.0.1 + +Use regular formatting instead: + +> Starcraft 9 +> +> Starcraft 9.0.1 + +Don't refer to changes in time when referring to a range of versions: + +> Starcraft 8 or newer +> +> earlier than core26 + +Use *higher* and *lower* instead: + +> Starcraft 8 or higher +> +> lower than core26 + +### Software and package names + +Don't format software and package names as code: + +> download and install `curl` +> +> the `firefox` snap +> +> `core26` + +Do write software names in plain English, using the spelling provided by the authors: + +> download and install curl +> +> the Firefox snap +> +> core26 + +Some commands, programs, and library names have become generic as verbs, tools, or products. For example, sudo and grep started as packages but have since entered common parlance. + +### Feature and component names + +Don't format feature and component names as code: + +> the `python` plugin +> +> the `gnome` extension + +Do format feature and component names plainly: + +> the Python plugin +> +> the GNOME extension + +The rule of thumb is, do you always qualify the name as belonging to the class of the feature? In other words, does it fit the pattern *the \[name\] \[feature type\]*? If yes, it should be formatted normally. + +### Code unit names + +Don't refer to code unit names without context: + +> call `setup()` +> +> if your package doesn't have a `name` + +Do qualify what the name is to disambiguate it: + +> call the `setup()` method +> +> if your package's `name` key isn't set + +## Links + +The prose of a document should be naturally-flowing, plain English. Whenever a link appears in the text, it threatens to harm that flow, because a link is an invitation to go somewhere else. Carefully consider: + +- How the link fits into the context of the preceding discussion. Does the text naturally lead to this link? Does it feel like it *belongs*? If you were having a conversation with a friend, and they pushed their phone up to your face without warning, it would be quite rude. That's what an unexpected link feels like on the page. +- What *benefit* the user gets from the link. A link is a call to action. But there are many actions the user could take in a document, including skipping the link. Does the link's text, and the text surrounding it, help the user decide whether to click on it? +- If you start writing "See \[link\] for more details", don't. That sentence is of no help to the user. Instead, consider how to invite, or call, the user to click on the link. + +Don't set high expectations or make promises you can't keep with a link: + +> You can visit [Migrations](https://docs.djangoproject.com/en/6.0/topics/migrations/) in the Django documentation to learn how to + +Do straightforwardly describe what's at the other end of the link: + +> [Migrations](https://docs.djangoproject.com/en/6.0/topics/migrations/) in the Django documentation describes how to + +It's better to be descriptive. You can't guarantee that a link will provide positive benefits like learning and discovery. + +### External link format + +For named external links, avoid end-of-file links: + +``` restructuredtext +`Migrations`__ + +# Rest of document... + +.. _Migrations: https://docs.djangoproject.com/en/6.0/topics/migrations/ +``` + +Prefer the inline format, with two underscores (\_): + +``` restructuredtext +`Migrations `__ +``` + +In long documents, the source is more readable, comprehensible, and easier to maintain when external links are declared in the same location as they're used. Internal references are formatted inline, so the authoring experience is more congruent with this pattern. + +The double underscore blocks Sphinx from making the external link into a named reference. + +### Examples of good links + +A link to another site: + +> Discuss your ideas on the [Snapcraft forum](https://forum.snapcraft.io). + +A link to an action in another how-to guide: + +> First, [install Brew](https://brew.sh#install). + +A link to a different section in the documentation: + +> Without such a connection, the snap fails to build. Guidance on sourcing information is available in `External package information +> `. + +A link to another documentation set: + +> The `snap` command itself has many diagnostic features that can help with debugging runtime and configuration errors. [Debugging snaps](https://snapcraft.io/docs/debug-snaps) in the SnapD documentation covers how and when to use them. + +## Reference labels + +Format Sphinx labels as: + +``` restructuredtext +.. _-- +``` + +For example: + +``` restructuredtext +.. _how-to-starcraft-style-guide-sphinx-labels +``` + +Within a documentation set, every label must be unique. A systematic and semantic approach reduces the chances for collisions and makes identification by humans much easier. + +Between documentation sets, they may be connected through Intersphinx. The namespaces of every connected documentation set are pooled. It's possible to have collisions if one set refers to another through a `:ref:` lookup instead of `:external+:ref:`. + +## Admonitions + +Wherever possible, avoid admonitions, also known as callouts, like notes, tips, cautions, and warnings. They compete for the user's attention and become noise when overused. Aim for at most one in a document. + +Prefer the generic admonition type: + +``` restructuredtext +.. admonition:: If you're thinking about using an admonition + :class: tip + + Try writing a plain paragraph first. +``` + +The message you put in the admonition becomes meaningful for its time and place, which is much more helpful to the user than a generic, context-free *Tip*. + +## Code blocks and quotations + +The purpose of code in documentation is to make bare the literal words and expressions that have effect in the software. Format code in contexts when you expect the user to immediately make use of it. + +Use as little code as possible. Readers have complete availability of our source code. They come to the documentation to read in a natural language. + +### Code directive + +Use the `code-block` directive for code blocks, and always include the language: + +``` restructuredtext +.. code-block:: bash + + ls -la +``` + +If no language applies, then the text probably isn't code, and different markup is needed. + +### Error messages + +Don't quote error messages and statuses as code: + +``` restructuredtext +.. code-block:: + + Code: macaroon-permission-required +``` + +Use the terminal directive instead: + +``` restructuredtext +.. terminal:: + :output-only: + + Code: macaroon-permission-required +``` + +## File paths + +Format file paths in text like this: + +> `/directory/from/root/` +> +> `relative/directory/` +> +> `path/to/file` +> +> `path/to/file.ext` + +There are many files in Linux that don't have extensions, such as `/bin/bash` and `~/.gitconfig`. Including the final slash makes it less ambiguous about whether we're describing a file or a directory. + +## Punctuation and symbols + +### Colons and semicolons + +Avoid colons and semicolons inside paragraphs: + +> There was only one thing to do: dance. +> +> It was cold; I ran home. + +Do use full stops: + +> There was only one thing to do. Dance. +> +> It was cold. I ran home. + +The grammar rules for when to use semicolons, colons, and commas vary between regions and writers. It's easier to sidestep them completely. + +Colons and semicolons are difficult to see when skimming, and are a barrier for blind users and those with vision impairment. + +Use colons to connect to an element on the next line: + +> Run the following commands to clear the cache: + +### Quotation marks + +Don't use quotation marks to cite terms, borrowed words, names, or titles: + +> also known as "crafting" a package +> +> according to "Design Patterns" + +Do use emphasis instead: + +> also known as *crafting* a snap +> +> according to *Design Patterns* + +Quotation marks around words can sound insincere or sarcastic. Many cultures and languages don't use them, so their meaning can be lost. + +### Non-linguistic symbols + +Don't use symbols as shorthand: + +> ✔ +> +> ✕ +> +> 🚀 + +Do use single words: + +> Yes +> +> No +> +> Launched + +Symbol meaning varies across cultures and languages. Symbols aren't always compatible in screen readers. + +## Preferred terms + +### Technical terms + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Instead of...Use...
applicationapp

Apt

+

apt

APT

craft tool

+

crafts

craft app

DEB

+

.deb

Debian package

keyword

+

field

key

+ +### Inclusive and nonviolent terms + +Some longstanding words in computing are biased, discriminatory, or violent. Use these replacements: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Instead of...Use...

black hat

malicious actor

+

attacker

blacklistblocklist
dummyplaceholder
grandfatheredexempt
hangstall
hitpress

illegal characters

invalid characters

+

unsupported characters

kill

+

terminate

end

+

halt

man-in-the-middlemachine-in-the-middle

master

primary

+

main

sanity check

safety check

+

confidence check

slave

secondary

+

replica

+

mimic

+

sample

+

example

white hat

researcher

+

security specialist

whitelistallowlist
diff --git a/.github/skills/documentation-build/SKILL.md b/.github/skills/documentation-build/SKILL.md new file mode 100644 index 00000000..859bb1aa --- /dev/null +++ b/.github/skills/documentation-build/SKILL.md @@ -0,0 +1,96 @@ +--- +name: documentation-build +description: "Validates documentation builds successfully. Use when checking Sphinx/RTD build integrity or diagnosing build failures. Reports errors, warnings, and build configuration issues." +--- + +# Documentation Build Validation + +## Scope + +Build validation only: detect documentation build configuration, +run applicable build targets, collect all errors and warnings, +and categorise by severity. + +## Inputs + +- Repository root. + +## Actions + +1. **Identify documentation directory**: The `docs/` directory + is the default location for Sphinx documentation. + If not found, search common doc roots in this order: + `doc/`, `documentation/`, `site/`, `docs-src/`. + If still not found, perform a bounded search for `conf.py` + (max depth 4) and use its parent as the docs root. + +2. **Detect build configuration**: Check for the presence of: + + - `.readthedocs.yaml` + - `docs/conf.py` + - Makefile targets in the `docs/` directory + + If RTD artefacts are absent in the target repository, + report "not applicable" in findings and exit cleanly. + +3. **Run build targets** (when applicable): + + ```bash + cd docs + make clean + make html + ``` + + Run additional checks for targets that exist. + Check each target before running to avoid false failures: + + ```bash + # Check and run each target if available + for target in spelling linkcheck woke lint-md; do + if make -n $target 2>/dev/null; then + make $target + fi + done + ``` + +4. **Capture output and handle failures**: If any command fails: + + 1. Capture the full error output from stderr and stdout + 2. Run `make clean` to reset build state + 3. Retry the failed build command once + 4. If retry fails, STOP and report all captured errors + 5. Do not proceed to content analysis until build succeeds + + Warnings must be collected and reported, but are not blocking + unless the repository explicitly treats warnings as errors. + +5. **Categorise findings by severity**: + + - **Errors**: Build failures, broken links, missing files. + - **Warnings**: Deprecation notices, missing references, + formatting issues. + - **Info**: Suggestions, minor notices. + +6. **Verify completion**: Confirm the validation completed: + + - Build targets were executed (or determined not applicable) + - Output was captured (errors and warnings) + - Findings were categorized by severity + + State the completion status: + - `✓ Build validation complete: [N] errors, [M] warnings found` + - OR `✓ Build validation complete: No issues found` + - OR `✓ Build validation: Not applicable - RTD artifacts not detected` + +## Constraints + +- Do not approve documentation that fails the Sphinx build. +- Build docs locally to catch build warnings. +- Do not invent Makefile targets; + only use targets confirmed to exist in the target repository. + +## Output + +A build validation report listing all errors and warnings, +categorised by severity. If RTD artefacts are not detected, +report "Not applicable -- RTD artefacts not detected in target repo". diff --git a/.github/skills/documentation-diataxis/SKILL.md b/.github/skills/documentation-diataxis/SKILL.md new file mode 100644 index 00000000..662f49c0 --- /dev/null +++ b/.github/skills/documentation-diataxis/SKILL.md @@ -0,0 +1,152 @@ +--- +name: documentation-diataxis +description: "Analyzes documentation against Diataxis framework (Tutorial, How-to, Reference, Explanation). Use when reviewing documentation structure or classifying content type. Identifies misalignments between declared category and actual content." +--- + +# Diataxis Classification Review + +## Scope + +Diataxis classification only: identify whether each page is a tutorial, +how-to guide, explanation, or reference; note structural mismatches +between content type and declared category, and suggest improvements +where real issues exist. +Ground classification in the Diataxis foundations: the two axes of craft +(action vs cognition, acquisition vs application) define four user needs +(learning, goals, information, understanding). + +This skill identifies flaws and provides actionable recommendations; +it does not enforce compliance or apply pass/fail criteria. + +## Inputs + +- Documentation file(s) under review. +- Diataxis framework principles (embedded in classification criteria below). + +## Actions + +1. **Identify intended category**: Determine the declared category + based on directory location + (`tutorial/`, `how-to/`, `explanation/`, `reference/`) + and file metadata (front matter keys such as `category`, `type`, + `diataxis`, or reST `.. meta::` entries). + +2. **Infer actual category**: Analyse the text's structure, tone, + and progression to determine which quadrant it actually resembles. + Use these classification criteria: + + - **Tutorial indicators**: + - Step-by-step progression building a complete project + - Imperative mood ("Create a file", "Run this command") + - Learning-focused language ("you will learn", "by the end") + - Safe, controlled environment (specific versions, no branching) + - Frequent reassurance and checkpoints + - Teaches by doing, not explaining + + - **How-to guide indicators**: + - Problem-solution format with clear goal + - Assumes existing knowledge and competence + - Clearly states prerequisites and applicability scope + - Action-oriented ("To achieve X, do Y") + - Flexible, allows for variation + - Focuses on results, not learning + - Omits explanations unless critical to success + + - **Reference indicators**: + - Descriptive, declarative statements + - Comprehensive coverage of subject + - Neutral, technical tone + - Structured for lookup (tables, lists, alphabetical) + - Parameters, options, API signatures + - Accuracy over narrative + + - **Explanation indicators**: + - Conceptual focus ("why" and "how it works") + - Discursive, exploratory tone + - Comparative analysis + - Context, background, relationships + - Illuminates understanding, not action + - May include history, design decisions, alternatives + - May contain subjective opinions and personal perspectives + +3. **Check user need alignment**: + + Map the page to the user need implied by the action/cognition and + acquisition/application axes (learning, goals, information, + understanding). + + - **Tutorials**: Is it a learning-oriented lesson? + Does it build confidence through doing? Is it linear and safe? + - **How-to guides**: Is it a task-oriented recipe? + Does it help a competent user solve a specific problem? + Is it goal-focused? + - **Reference**: Is it information-oriented? + Does it describe things accurately and completely? + Is it structured for lookup? + - **Explanation**: Is it understanding-oriented? + Does it clarify concepts, context, and relationships? + Is it discursive? + +4. **Note hard-to-fit genres**: Some documentation types do not align + cleanly with a single quadrant (for example, release notes or + contributing guides). Flag these cases explicitly, reference the + Diataxis guidance on complex hierarchies + (https://diataxis.fr/complex-hierarchies/), and choose the closest + fit category for reporting. + +5. **Evaluate quality**: + + - **Functional quality**: Is the content accurate, complete, + consistent, useful, and precise? + - Missing prerequisites or dependencies + - Incomplete steps or procedures + - Inconsistent terminology or naming + - Outdated information (version mismatches, deprecated features) + + - **Deep quality**: Does the content have good flow? + Does it anticipate user questions? + Is the cognitive load appropriate? Is the experience clear? + - Paragraph length (>4 sentences may suggest need for breaking) + - Sentence complexity (nested clauses, dense jargon) + - Transition quality (abrupt topic changes, missing connectives) + - Progressive disclosure (introducing too much too soon) + - User journey mapping (gaps in expected flow) + +6. **Document misalignments**: Explicitly identify where the document + fails to meet the needs of its category, jumps between categories, + or where quality breaks down. For each issue, provide: + - Specific location (section, paragraph) + - Nature of the problem + - Impact on user experience + - Concrete suggestion for improvement + +7. **Verify completion**: Confirm the analysis completed: + + - Category classification completed (declared vs inferred) + - User need alignment analyzed + - Quality assessment performed (functional and deep quality) + - Misalignments documented with recommendations + + State the completion status: + - `✓ Diataxis analysis complete: [declared category] → [inferred category], [N] issues found` + - OR `✓ Diataxis analysis complete: Content aligns well with [category]` + +## Constraints + +- Do not ignore the Diataxis framework. +- Assign each page to exactly one quadrant. +- Do not introduce categories beyond the four quadrants. + +## Output + +A Diataxis Analysis Report detailing: + +- Declared category (from metadata/directory structure). +- Inferred category (from content analysis). +- User need alignment analysis (which quadrant best serves the user). +- Functional quality findings (with specific examples). +- Deep quality findings (with specific examples). +- Identified issues and actionable recommendations for improvement. + +If no significant issues are found, state that the documentation +aligns well with its intended category. diff --git a/.github/skills/documentation-review/SKILL.md b/.github/skills/documentation-review/SKILL.md new file mode 100644 index 00000000..15b9e6f9 --- /dev/null +++ b/.github/skills/documentation-review/SKILL.md @@ -0,0 +1,198 @@ +--- +name: documentation-review +description: "Performs comprehensive documentation review including build validation, Diataxis analysis, structure audit, accuracy verification, and style compliance. Use when reviewing documentation changes or auditing documentation quality." +--- + +# Documentation Review + +## Scope + +Orchestration only: defines the end-to-end review workflow, +specifies the order in which atomic skills are invoked, +and renders the final consolidated report using the report template +at `references/doc-review-report-template.md`. + +## Persona + +You are a technical documentation reviewer and editor for the project. +Your job is to ensure the documentation is clear, accurate, +consistent with code, and follows the project's style guide. +You apply the Diataxis framework +(Tutorial, How-to, Explanation, Reference) rigorously. + +## Workflow + +Follow these stages sequentially. **Do not skip stages.** + +### Execution Requirements + +**CRITICAL:** After completing each stage, you MUST: +1. Confirm the skill was actually invoked (not just described) +2. Capture the output and record findings +3. State the completion status explicitly + +**Verification Pattern:** +After each stage, state: +- `✓ Stage [N] complete: [skill-name] generated [N] findings` +- If no findings: `✓ Stage [N] complete: [skill-name] found no issues` + +**Do NOT proceed to Stage [N+1] until Stage [N] is verified complete.** + +--- + +### Stage 1: Build Validation + +**Execute:** Use the `documentation-build` skill to validate the documentation build. + +**Capture:** Record all build errors and warnings. + +**Verify:** Confirm build status (pass/fail) before proceeding. + +**Decision Point:** If the build fails, report build issues immediately and STOP. Do not proceed to content analysis until the documentation builds without errors. + +**Checkpoint:** `✓ Stage 1 complete: documentation-build [passed/failed with N errors]` + +--- + +### Stage 2: Documentation Structure Discovery + +**Execute:** Map the documentation structure before analyzing content. + +**Actions:** +1. List all documentation files under `docs/` (or equivalent) +2. Identify the documentation build system (Sphinx, MkDocs, Jekyll, etc.) +3. Note the directory structure (flat vs. categorized) +4. Record any metadata patterns (frontmatter, sidebar configs) + +**Output:** Store this structural map internally for use in later stages. + +**Checkpoint:** Confirm you have identified: +- [ ] Documentation root directory +- [ ] Build system type +- [ ] File organization pattern +- [ ] Metadata conventions (if any) + +Then state: `✓ Stage 2 complete: Structure mapped ([N] files in [system] with [pattern] organization)` + +--- + +### Stage 3: Diataxis Classification + +**Execute:** Use the `documentation-diataxis` skill to analyze each documentation page. + +**Capture:** Record the declared category (from metadata/directory) and inferred category (from content analysis) for each page. + +**Verify:** Confirm you have classification results for all documentation pages analyzed. + +**Checkpoint:** `✓ Stage 3 complete: documentation-diataxis analyzed [N] pages, found [N] misalignments` + +--- + +### Stage 4: Structure Audit + +**Execute:** Use the `documentation-structure` skill to validate documentation organization. + +**Input Required:** Use the Diataxis classification output from Stage 3 to validate directory placement. + +**Capture:** Record all structural violations (file naming, metadata, directory placement, navigation, cross-references). + +**Verify:** Confirm structural audit completed for all pages. + +**Checkpoint:** `✓ Stage 4 complete: documentation-structure found [N] violations` OR `✓ Stage 4 complete: documentation-structure found no violations` + +--- + +### Stage 5: Accuracy Verification + +**Execute:** Use the `documentation-verify` skill to cross-reference documentation claims against source code. + +**Capture:** Record all accuracy findings grouped by classification (unsupported, outdated, incorrect, imprecise, speculative, inconclusive). + +**Verify:** Confirm code verification completed for all claims in changed documentation. + +**Checkpoint:** `✓ Stage 5 complete: documentation-verify found [N] accuracy issues` OR `✓ Stage 5 complete: documentation-verify found no accuracy issues` + +--- + +### Stage 6: Style Review + +**Execute:** Use the `documentation-style` skill to evaluate documentation against the project style guide. + +**Capture:** Record all style violations with quoted passages from the style guide. + +**Verify:** Confirm style review completed for all documentation. + +**Checkpoint:** `✓ Stage 6 complete: documentation-style found [N] style violations` OR `✓ Stage 6 complete: documentation-style found no style violations` + +--- + +### Stage 7: Consolidated Report + +**Execute:** Synthesize findings from all stages into a structured, actionable review using the report template at `references/doc-review-report-template.md`. + +**Assembly Instructions:** + +For each skill output, extract findings and populate the corresponding report section: + +| Skill | Report Section | Format | +|-------|----------------|--------| +| documentation-build | Build Findings | List of errors/warnings or "No issues found" | +| documentation-verify | Accuracy Findings | Grouped by classification (unsupported/outdated/incorrect/imprecise) | +| documentation-diataxis | Diataxis Findings | Table of declared vs inferred categories, list misalignments | +| documentation-structure | Structure Findings | List of violations or "No issues found" | +| documentation-style | Style Findings | List of violations with quoted style guide passages | + +**Handling Empty Results:** +- If a skill produces no findings: Write "No issues found" in that section +- If a skill is not applicable: Write "Not applicable - [reason]" (e.g., "Not applicable -- RTD artefacts not detected") + +**Priority Order:** Present findings in priority order (highest priority first): + +1. **Build Findings (BLOCKING)** - Must be resolved before content analysis +2. **Accuracy Findings (CRITICAL)** - Code-documentation mismatches +3. **Diataxis Findings (HIGH)** - Category misalignments affecting usability +4. **Structure Findings (MEDIUM)** - Organizational and navigation issues +5. **Style Findings (LOW)** - Style guide compliance + +**Checkpoint:** `✓ Stage 7 complete: Consolidated report generated with findings from [N] stages` + +--- + +## Error Handling + +If a stage fails to complete, handle as follows: + +### Build Validation Failure +- Report build errors immediately +- STOP the workflow - do not proceed to content analysis +- Include build errors in the final report + +### Skill Invocation Errors +- Report the error in the corresponding report section +- Continue with remaining stages +- Note the failure in the Summary section + +### Missing Dependencies +- Report what's missing (e.g., "Style guide not found at docs/style-guide.md") +- Mark that stage as "Incomplete" in the report +- Continue with other stages + +### Incomplete Stages +If any stage could not be completed, add an "Incomplete Stages" section to the report listing: +- Which stage failed +- Why it failed +- What's needed to complete it + +--- + +## Constraints + +- Provide criticism and suggestions rather than direct bulk rewrites. +- Do not modify source code to fix documentation + without explicit request. +- Before restructuring large documentation sections + (for example, moving files between tutorial and how-to), ask first. +- Before suggesting new coverage entities, categories, + or metadata patterns, ask first. +- If code examples seem correct + but do not match your understanding of the codebase, ask first. diff --git a/.github/skills/documentation-review/references/doc-review-report-template.md b/.github/skills/documentation-review/references/doc-review-report-template.md new file mode 100644 index 00000000..c872ecb6 --- /dev/null +++ b/.github/skills/documentation-review/references/doc-review-report-template.md @@ -0,0 +1,68 @@ +## Documentation Review Report + +**Reviewed:** + +**Date:** + +**Skills Applied:** + +--- + +### Build Findings (BLOCKING) + +*Source: documentation-build* + + + +--- + +### Accuracy Findings (CRITICAL) + +*Source: documentation-verify* + + + +--- + +### Diataxis Findings (HIGH) + +*Source: documentation-diataxis* + + + +--- + +### Structure Findings (MEDIUM) + +*Source: documentation-structure* + + + +--- + +### Style Findings (LOW) + +*Source: documentation-style* + + + +--- + +### Incomplete Stages + +*Only include this section if any stage failed to complete* + + + +--- + +### Summary + + + +**Recommended Action Priority:** +1. Resolve blocking build issues first +2. Fix critical accuracy/code-backing issues +3. Address high-priority Diataxis misalignments +4. Resolve structural issues +5. Apply style corrections diff --git a/.github/skills/documentation-structure/SKILL.md b/.github/skills/documentation-structure/SKILL.md new file mode 100644 index 00000000..c0b07580 --- /dev/null +++ b/.github/skills/documentation-structure/SKILL.md @@ -0,0 +1,79 @@ +--- +name: documentation-structure +description: "Validates documentation structural integrity including heading hierarchy, metadata, file naming, navigation, and cross-references. Use when checking documentation organization or validating toctree structure." +--- + +# Documentation Structure Audit + +## Scope + +Document structure only: heading hierarchy, section ordering, +presence of required sections (introduction, prerequisites, steps, reference), +file naming, metadata blocks, navigation, and cross-references. + +## Inputs + +- Documentation file(s) under review. +- Documentation directory structure. +- Diataxis classification output + (from the `documentation-diataxis` skill, when run as part of the orchestrated review). + +## Actions + +1. **File Naming**: + + Verify files use lowercase with dashes + and the correct extension for their syntax + (for example, `connect-vscode.rst` for reST, `connect-vscode.md` for MyST). + +2. **Metadata**: + + Ensure every page has required metadata near the top + when the repository's docs conventions require it: + `.. meta::` after the anchor label for reST, + or the MyST equivalent (front matter or `meta` directive) for Markdown sources. + +3. **Directory Placement**: + + Confirm the file is located in the directory matching its intended + Diataxis category + (for example, tutorials in `tutorial/`, how-to guides in `how-to/`). + +4. **Navigation**: + + Ensure new pages are added to the `toctree`. + +5. **Cross-References**: + + - Prefer stable reference roles + (`:ref:` for reST, `{ref}`/`{numref}` for MyST) over page-level links. + - Flag uses of `:doc:`/`{doc}` (or equivalents) + except for index-like pages that are unlikely to be moved or renamed. + - Suggest adding links to improve documentation discoverability. + - Verify cross-references resolve correctly. + +6. **Verification**: + + Confirm the structural audit completed: + + - File naming checked for all files + - Metadata presence verified + - Directory placement validated (using Diataxis classification if available) + - Navigation structure checked (toctree entries) + - Cross-references validated + + State the completion status: + - `✓ Structure audit complete: [N] violations found` + - OR `✓ Structure audit complete: No violations found` + +## Constraints + +- Do not modify files during the audit; this is a read-only review. +- Do not invent metadata requirements; check against repository's documented conventions. +- Focus on structural issues only; do not flag style preferences. +- When Diataxis classification is available (from orchestrated review), use it to validate directory placement. Otherwise, infer from directory name. + +## Output + +A list of structural or metadata violations covering file naming, +metadata, directory placement, navigation, and cross-reference issues. diff --git a/.github/skills/documentation-style/SKILL.md b/.github/skills/documentation-style/SKILL.md new file mode 100644 index 00000000..6e0364bc --- /dev/null +++ b/.github/skills/documentation-style/SKILL.md @@ -0,0 +1,74 @@ +--- +name: documentation-style +description: "Enforces project documentation style guide compliance for tone, voice, terminology, punctuation, and formatting. Use when checking documentation style or validating MyST/reST syntax. Cites specific style guide violations." +--- + +# Documentation Style Review + +## Scope + +Style conformance only: tone, voice, terminology, punctuation, +Oxford comma, active versus passive voice, prohibited phrases, +and formatting conventions. + +## Inputs + +- Documentation file(s) under review. +- Normative style asset: `references/doc-style-guide.md`. +- Syntax-specific style guides (fetched at runtime): + - MyST: `https://raw.githubusercontent.com/canonical/sphinx-docs-starter-pack/refs/heads/main/docs/reference/myst-syntax-reference.md` + - reST: `https://raw.githubusercontent.com/canonical/sphinx-docs-starter-pack/refs/heads/main/docs/reference/rst-syntax-reference.rst` + +## Actions + +1. **Load style guides**: Read `references/doc-style-guide.md`. + Fetch the syntax-specific guide matching the file type + (MyST for `.md`, reST for `.rst`). + +2. **Syntax compliance**: Check headings, lists, code blocks, + inline literals, and directives against the applicable syntax guide. + Treat every instruction in the guide as mandatory; + do not rely on a subset of rules. + +3. **Full style guide compliance**: Read and apply all rules defined + in `references/doc-style-guide.md`. + Treat every instruction in the guide as mandatory; + do not rely on a subset of rules. + +4. **Style guide citation**: For every violation found, + locate and quote the specific passage + in `references/doc-style-guide.md` or the syntax-specific guide + that supports the finding. + +5. **Fallback behaviour**: If syntax guides cannot be fetched + (offline or network blocked), continue the review + using `references/doc-style-guide.md` + and the syntax patterns already present in the documentation set. + + If `references/doc-style-guide.md` is unavailable, + STOP the review and report that the style guide cannot be accessed. + +6. **Verification**: + + Confirm the style review completed: + + - Style guides loaded (doc-style-guide.md and syntax-specific guide if available) + - Syntax compliance checked against applicable guide + - Style guide compliance checked against all rules in doc-style-guide.md + - All violations cited with quoted passages from style guides + + State the completion status: + - `✓ Style review complete: [N] violations found` + - OR `✓ Style review complete: No violations found` + +## Constraints + +- Quote style guides when making style suggestions. +- Do not suggest style or markup changes without quoting the style guides. + +## Output + +A list of style violations, each accompanied by: + +- The specific passage quoted from the style guide or syntax reference. +- The observation or suggested change. diff --git a/.github/skills/documentation-style/references/doc-style-guide.md b/.github/skills/documentation-style/references/doc-style-guide.md new file mode 100644 index 00000000..03fe3852 --- /dev/null +++ b/.github/skills/documentation-style/references/doc-style-guide.md @@ -0,0 +1,643 @@ +```{eval-rst} +:orphan: + +.. meta:: + :description: Documentation style guide covering file naming, + structure, semantic line breaks, reStructuredText and Markdown + conventions, terminology, and project-specific patterns. +``` + + + +# Documentation style guide + +This style guide documents the established conventions used in the project documentation. It captures actual patterns observed across the documentation set and serves as a reference for maintaining consistency in new contributions. + +This guide is subordinate to your organization's documentation standards but records project-specific decisions and patterns that extend or clarify those standards. + +--- + +## File naming and organization + +**Directory structure** + +The documentation follows the [Diátaxis](https://diataxis.fr/) framework with four main sections: + +``` +docs/ +├── tutorial/ # Step-by-step learning paths +├── how-to/ # Task-oriented guides +├── explanation/ # Conceptual information +└── reference/ # Technical specifications +``` + +**File naming convention** + +All filenames use lowercase letters and dashes for word separation. + +Examples: + +- Good: `part-1-get-started.rst` +- Good: `connect-editor.rst` +- Good: `network-interface.rst` +- Good: `container-vs-dockerfile.rst` +- Avoid: `ConnectEditor.rst` (uppercase) +- Avoid: `network_interface.rst` (underscore) + +Optional: Tutorial files may use a sequential numbering pattern: + +``` +part-1-get-started.rst +part-2-work-with-features.rst +part-3-advanced-concepts.rst +part-4-production-deployment.rst +``` + +How-to files: Use verb-first naming pattern: + +``` +add-configuration.rst +connect-editor.rst +forward-ports.rst +debug-issues.rst +resolve-conflicts.rst +``` + +Explanation files use noun-based naming: + +``` +concepts.rst +interface-concepts.rst +best-practices.rst +runtime-behavior.rst +``` + +Reference files match command structure: + +``` +command-launch.rst +command-connect.rst +build-tool.md +``` + +Filenames and directory names in the documentation repo should be in lowercase, +with dashes instead of spaces; the directory tree must be built in a way that +provides for readable, meaningful URLs: `/docs/howto/change-tyres`. + +--- + +## Page structure and metadata + +**Standard page structure** + +Every documentation page follows a consistent structure: +anchor label, metadata block, page title, opening paragraph, and section hierarchy. +Use the syntax references for exact markup and placement details. + +**Metadata block** + +Every page must have a metadata block immediately after the anchor label. +Use a brief, clear description (typically 1-2 lines), +wrapping at natural phrase boundaries. + +**Anchor labels** + +Use lowercase with underscores or dashes. + +Optional: Prefix labels with section type. +Use prefixes consistently across the docs. + +Prefixes: + +- `tut_` - Tutorial sections +- `how_` - How-to guides +- `exp_` - Explanation articles +- `ref_` - Reference documentation + +Examples: `tut_get_started`, `how_add_actions`, `exp_interface_concepts`, `ref_command_launch`. + +--- + +## Writing style and tone + +**Voice and audience** + +Target audience is developers and technical professionals seeking to: + +* Achieve specific goals without much overhead and roundabout musings +* Perform and conceive complex ad-hoc tasks and workflows that require precision and depth +* Attain understanding of the project's key capabilities beneficial for their scenarios + +Content follows the Diátaxis framework, providing: + +* Concise tutorials for common, starter-level actions and scenarios, eliminating the need to invent custom steps and allowing novice users to journey along the hot path effortlessly +* Elaborate explanations of the thinking behind the project's design, including design decisions, related concepts, and how it should be used +* Detailed how-to guides that address specific needs of advanced users and cover topics beyond basic entry-level operations +* Comprehensive reference of all options, settings, and details available to customize the project's operation in any desirable manner + +The tone is authoritative but relaxed, confident but approachable. Think water cooler conversation, not classroom session. + +Example: + +```text + is a tool for defining and handling development environments. + +List your dependencies and components in YAML to define an environment. The key pieces of a definition are components, independent but connectable units of functionality. The project simplifies experiments with your environment layout. +``` + +**Active and passive voice** + +Use active voice for user actions and cause-effect relationships. Use passive voice when the agent is unknown or the effect is the focus. + +Active voice examples (preferred for actions): +- "The server hosts all files" +- "You install apps with the App Center" +- "The validate library checks the form for errors" + +Passive voice examples (appropriate for effects): +- "Before upload, the form is checked for errors" +- "The files are deleted every time the script runs" + +Pattern recognition: Passive voice uses `is/are/was/were/been/being + past participle` (e.g., "is installed", "are checked"). + +**Direct instructions** + +Use imperative mood for instructions. Avoid "you can" or "you may" for required actions. + +Preferred: + +``` +Install the application using the `--classic` option: +``` + +Avoid: + +``` +You can install the application with: +``` + +**Paragraph length** + +Keep paragraphs focused and relatively short (2-5 sentences typically). Complex topics should be broken into multiple paragraphs. + +Example: + +```restructuredtext +Install the project, +upgrading the prerequisites if needed, +then ensure it runs. + +Authenticate to the package manager and install +using the required options: +``` + +**Paragraph structure (optional)** + +Where suitable, structure paragraphs using the Topic-Development-Example-Summary (TDES) pattern: + +1. **Topic**: Open with a clear statement of what the paragraph addresses +2. **Development**: Explain the concept or provide necessary context +3. **Example**: Illustrate with a concrete example +4. **Summary**: Close with the key takeaway or implication + +This pattern is particularly effective for explanatory content but should be applied flexibly; not every paragraph requires all four elements. + +Example applying TDES: + +```text +Interfaces enable communication between components and the host system. +Each interface defines a specific capability, such as network access or GPU usage. +For instance, the `network` interface allows a component to access external services, +while the `gpu` interface provides access to hardware acceleration. +Using interfaces, you can precisely control what resources each component can access. +``` + +In practice, simpler paragraphs may use just Topic-Example or Topic-Development, depending on the content's purpose and complexity. + +**Clarity over cleverness** + +- State prerequisites explicitly +- Define terms at first use +- Avoid assumptions about reader knowledge +- Use precise, unambiguous language + +**Words and phrases to avoid** + +Avoid clichés, violent metaphors, and jargon. Replace them with simpler alternatives: + +- **Clichés** + - `the ability to`, `is able to` → `can` + - `in order to` → `to` + - Avoid: `allow`, `going forward`, `not only...but also` + +- **Violent metaphors** + - `kill`, `terminate` → `stop` + - `execute` → `run` + - `eliminate` → `remove` + +- **Jargon** + - `leverage` → `use` + - `end user` → `user` + - `use case` → `example` or `scenario` + - Avoid: `ecosystem`, `form factor`, `harness`, `next level` + +This is not an exhaustive list; use your best judgment. + +**Latin words and phrases** + +Replace Latin phrases with English equivalents: + +- `e.g.` → `for example`, `such as` +- `i.e.` → `that is`, `in other words` +- `etc.` → `and so on` +- `via` → `through`, `with`, `using` +- `ad hoc` → `unscheduled`, `temporary`, `bespoke` +- `per se` → `necessarily`, `intrinsically` +- `versus`, `vs.` → `compared to`, `opposed to` +- `vice versa` → `the reverse`, `the other way around` +- `circa` → `around`, `near` +- `cf.` → `refer to` + +This is not an exhaustive list; use your best judgment. + +**Demonstrative pronouns** + +Avoid orphan "this", "these", "those", "that" when ambiguous. Pair with the noun for clarity. + +Good: "The `yaml` object is sourced from the `yamllib` library. This object is only available if..." + +Avoid: "The `yaml` object is sourced from the `yamllib` library. This is only available if..." (unclear if referring to object or library) + +**Language and spelling** + +Convention: Use US English spelling, grammar, and formatting conventions throughout the documentation. + +Common US/UK differences: +- Patterns: `-ize` (not `-ise`), `-or` (not `-our`), `-able` (not `-eable`) +- US: `license` (noun and verb), `defense`, `program`, `percent`, `skeptical`, `catalog`, `traveling`, `labeled` +- UK: `licence` (noun), `defence`, `programme` (non-IT), `per cent`, `sceptical`, `catalogue`, `travelling`, `labelled` + +Common technology terms: +- `email`, `online`, `website`, `internet` +- `setup` (noun), `set up` (verb) +- `backup` (noun), `back up` (verb) +- `login` (noun), `log in` (verb) +- `space-separated`, `comma-delimited` +- `open source` (noun), `open-source` (adjective) + +Examples: +- Good: `color`, `center`, `analyze`, `behavior` +- Avoid: `colour`, `centre`, `analyse`, `behaviour` +- Good: Use serial comma: "components, interfaces, and environments" +- Good: Double quotes for quotations: "The project is a tool" + +**Contractions** + +Acceptable: `aren't`, `can't`, `couldn't`, `didn't`, `doesn't`, `don't`, `hadn't`, `hasn't`, `haven't`, `isn't`, `it's`, `mustn't`, `wasn't`, `won't`, `wouldn't`, `you're`, `you've`, `you'll`, `we're`, `we've` + +Forbidden: `ain't` (colloquial), `gonna`, `gotta`, `something's` (confusion with possessive), `I'd`, `I'll` (avoid first person) + +**Dates and numbers** + +Date format: +- Single day: `1 January 2013` +- Range within month: `1-2 January 2013` +- Range across months: `1 January - 2 February 2013` + +Numbers: +- Spell out below 10: `seven servers` +- Use digits from 10 onwards: `15 containers` +- Exception: Always use digits for units of measurement: `5 GB`, `3 seconds` +- Use commas for thousands: `7,000` not `7000` + +--- + +## Semantic line breaks (optional) + +**Pattern** + +The documentation consistently uses semantic line breaks (one line per clause or significant phrase) in reStructuredText files. This improves version control diffs and editing precision. + +Rationale: Semantic breaks make git diffs more readable and help reviewers identify exactly what changed in a sentence or paragraph. + +**Implementation** + +Break lines at natural semantic boundaries: +- After each complete clause +- Before coordinating conjunctions (and, but, or) +- Before relative clauses (which, that, who) +- After introductory phrases + +Example: + +```restructuredtext +This is the first section of the :ref:`four-part series `; +a practical introduction +that takes you on a tour +of the essential |project_markup| activities. +``` + +MyST equivalent: + +````markdown +This is the first section of the {ref}`four-part series `; +a practical introduction +that takes you on a tour +of the essential |project_markup| activities. +```` + +**When to break** + +Break after: +- Complete independent clauses +- Introductory prepositional phrases +- Transitional phrases +- Items in a complex series + +Keep together: +- Short phrases that form a single unit +- Inline markup and its target word +- Cross-reference markup + +Example: + +```restructuredtext +Interfaces are a mechanism for communication and resource sharing. +It is an integral part of environment isolation, +ensuring that each environment operates in its own isolated context, +while still allowing controlled interactions among the components and with the host. +``` + +--- + +## Headings and titles + +**Capitalization** + +Pattern: Sentence case for all headings (capitalize only first word and proper nouns). + +Exception: Product names and proper nouns maintain their capitalization. + +**Heading constraints** + +- Headings must not end with a period +- Avoid links in headings +- Use `code` styling sparingly in headings (only when essential, such as command references) +- Headings must not be followed directly by a subheading (provide introductory content) +- Do not skip heading levels (e.g., h1 followed by h3) + +**How-to title pattern** + +How-to guides follow the pattern: "How to [action] [object]" and use imperatives, not gerunds: +- Good: "How to create an instance" (imperative) +- Avoid: "How to creating an instance" or "Creating an instance" (gerund) +- How to forward ports with tunneling +- How to fix connection conflicts +- How to debug issues in environments + +Linking exception: In navigation and links, drop "How to" prefix and use infinitive: + +```restructuredtext +How-to guides: + +* Debug issues in environments +* Connect IDE to an environment +``` + +--- + +## Markup and formatting policies + +Use the syntax references for markup details. +Apply the policies below for project-specific conventions. + +**Admonition placement:** Place admonitions at the end of the subsection they relate to, rather than interrupting the flow of text in the middle of a section. This is especially relevant for multiple admonitions per section. + +**Inline markup** + +Semantic markup preference: Use semantic markup roles (for example, sample values, environment variables, file paths, commands, GUI labels, and programs) instead of generic emphasis. Choose the most specific role that suits the purpose and use it consistently. + +Use italics sparingly to introduce new terms and for emphasis. Leave bold for product names and commands. + +Commands in command roles should be presented in their complete form and should not be used as verbs or nouns in the text. +Use non-breaking spaces to prevent longer compound commands from wrapping. + +End directory path names with a slash where possible and conventional to disambiguate directories from files. + +Format placeholders in uppercase within angle brackets, without underscores. + +**Non-breaking spaces:** Use non-breaking spaces for important proper names and compound commands where line breaks would be awkward. + +**"See also" sections (optional)** + +"See also" sections can appear on pages under any pillar and link to related content not immediately essential but potentially useful. Break link lists down by pillar, listing pillars and individual subsections in alphabetical order. + +**Tab headings** + +Pattern: Keep tab headings noun-based and consistent across related content. Avoid unintended "sticky toggling" (where tab state persists inappropriately across different contexts). + +**Sphinx extensions and roles** + +Preference: Use Sphinx-specific [roles](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html) and [directives](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html) over `docutils` generic equivalents. Use all their options and capabilities, listing options in alphabetical order. + +**Spacing and formatting** + +Section gaps: Include a non-cumulative two-line gap (two blank lines) after code samples, lists, tables, and before headings for visual clarity. + +--- + +**Simplified markup for GitHub** + +Use simplified markup for files that have special meaning on GitHub and need to be rendered there (such as `README.md`, `CONTRIBUTING.rst`, `SECURITY.rst`). For example, don't use `$` prompts in command samples for these files because GitHub doesn't prevent their selection during copying, which can confuse users. + +--- + +**Command prompts and code blocks** + +**DO NOT** use `$` or `#` prompts in code samples except when using the `console` lexer, which makes them non-selectable. Prompts cause problems for users who copy-paste code. + +It is ONLY acceptable to use the `$` prompt when it's non-selectable. The `console` lexer in `.. code-block::` automatically handles this, making the prompt non-selectable during copy operations. + +**Avoid inline comments** in bash code blocks. Use prose before, after, or between code blocks instead: + +Avoid: + +```bash +juju deploy wordpress +juju deploy ntp-master --to 2 # colocates with wordpress +``` + +Preferred: + +``` +Deploy wordpress, then colocate ntp-master with it: +``` + +```bash +juju deploy wordpress +juju deploy ntp-master --to 2 +``` + +**Code block length**: Limit code blocks to approximately 40 lines. Longer blocks are rarely read; consider breaking them up or offering as downloadable files. + +**Separate input and output**: Don't combine commands and their output in one block. Separate them with explanatory text: + +Avoid: + +``` +juju status +environment: gce3 +machines: +... +``` + +Preferred: + +``` +Check the current state: +``` + +```bash +juju status +``` + +``` +This returns the current state of each unit: +``` + +``` +environment: gce3 +machines: +... +``` + +**Placeholders** + +Use uppercase within angle brackets for placeholders: ``, `` + +For longer code blocks, consider defining placeholders as environment variables: + +```bash +CHANNEL=1.30/stable +``` + +Then use them in commands: + +```bash +juju download easyrsa --channel=$CHANNEL +juju download kubernetes-worker --channel=$CHANNEL +``` + +This approach: +- Separates user-supplied data from commands +- Enables blocks to be copied without modification +- Reduces the chance of user errors + +**UI interaction guidance** + +Don't use UI elements as verbs or nouns in prose. Link them to actions: + +- Good: "Click **Save** to save your settings" +- Avoid: "**Save** your settings" (using button text as verb) + +**Interaction verbs**: +- Use `Click` for buttons (or `Tap` for primarily mobile products) +- Use `Select` for dropdowns, multiple options, or menu navigation +- Use `Press` for keyboard shortcuts and keys (NOT `Click`) + +Examples: +- Click **Settings** to open user settings +- Select the machines you want to register, then click **Save** +- Press `Ctrl + C` to copy +- Press the `Enter` key to continue +- Select **Preferences > Languages > English** (using `>` for navigation) + +**Formatting**: +- Bold UI elements: **Save**, **File**, **Settings** +- Use `>` for menu navigation: **File > New > Document** +- Italics for quoted UI text: Click the link in _"You can register new computers..."_ + +**Checkboxes**: Use `Select`/`Clear` or `Check`/`Uncheck` (consistent pairs): +- Select the **Enable firewall** checkbox +- Clear the **Add bookmark** checkbox + +**Icons vs buttons**: Minimize use of "icon" and "button" terminology unless needed for clarity. When using images, provide alt text or write the name directly after. + +**Configuration examples** + +Always include caption when known. + +Indentation: Use commonly recognized formatting: +- YAML files: 2-space indentation +- JSON files: 4-space indentation + +**Multi-line shell commands** + +Use backslash continuation or explicit line breaks: + +--- + +## Cross-references and links + +**Internal cross-references** + +Prefer `:ref:`/`{ref}` with semantic anchor labels. +Use `:doc:`/`{doc}` only when no target exists and no target can be added, +such as pages intentionally designed without anchors (for example, index or release notes). + +**First mention pattern** + +Link important terms only at first mention on a page. Avoid excessive linking. + +**Reference label convention** + +Use the following pattern for anchor labels: `.. _{prefix}_{descriptive_name}:`. +Prefix indicates the section type (ref/how/exp/tut). + +--- + +**Command names** + +In example blocks, use exact subcommand syntax: + +``` +project-tool launch +project-tool connect +build-tool build +``` + +When inline, shorter references are acceptable: the `launch` command. + +**Command line terminology** + +Convention: Use [POSIX utility conventions](https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html) when discussing command-line syntax, options, arguments, and other CLI elements. + +--- + +## Documentation quality principles + +Use the following in addition to general Diátaxis guidelines: + +**Clarity** + +- State assumptions explicitly +- Define prerequisites clearly +- Avoid jargon without explanation +- Use consistent terminology + +**Usability** + +- Focus on actionable information +- Use direct imperatives for instructions +- Break complex tasks into clear steps +- Provide working examples + +**Precision** + +- Avoid ambiguous language +- Use exact commands and syntax +- Specify versions when relevant +- Maintain consistent structure diff --git a/.github/skills/documentation-verify/SKILL.md b/.github/skills/documentation-verify/SKILL.md new file mode 100644 index 00000000..18ee4243 --- /dev/null +++ b/.github/skills/documentation-verify/SKILL.md @@ -0,0 +1,80 @@ +--- +name: documentation-verify +description: "Verifies documentation accuracy by cross-referencing claims, CLI commands, API signatures, and configuration against source code. Use when validating documentation correctness or checking code-docs consistency. Flags unsupported or outdated claims." +--- + +# Documentation Accuracy Verification + +## Scope + +Accuracy verification only: cross-reference documentation claims, commands, API names, and configuration keys against source code in the same repository. Flag anything that cannot be verified. + +## Inputs + +- Changed documentation files (from `git diff`). If `git diff` is unavailable or empty, use files explicitly provided for review; otherwise, treat all documentation files under `docs/` as changed. +- Full codebase. +- Test files, configuration schemas. +- Documentation structure. + +--- + +## Workflow + +Follow this three-stage process to verify documentation accuracy: + +### Stage 1: Discovery Scan + +**Objective**: Identify documentation claims and form initial hypotheses. + +1. Run `git diff` to list changed documentation files. +2. Categorize changes into claim types (behaviour, CLI, API, config, examples, error messages, etc.). +3. Form initial hypotheses: Supported, Unsupported, Speculative, Ambiguous, or Outdated. + +**For detailed categorization and hypothesis formation procedures**, see `references/verification_procedures.md` → Discovery Scan. + +--- + +### Stage 2: Verification Pass + +**Objective**: Verify every hypothesis with code evidence. Code is the source of truth. + +**CRITICAL**: Complete verification before reporting any claims. + +1. Use **at least two search strategies** per claim (direct search, entrypoint tracing, test evidence, schema/validation search). +2. Apply claim-type-specific verification checklists (behaviour, CLI, API, config, examples, errors, terminology). +3. Document evidence for each finding (file paths, line numbers, search commands). +4. Reclassify hypotheses based on verification results. +5. Apply false-positive prevention rules. +6. Cross-check documentation coverage. + +**For comprehensive verification checklists and classification rules**, see `references/verification_procedures.md` → Verification Pass. + +--- + +### Stage 3: Report Generation + +**Objective**: Present verified findings with evidence and conservative recommendations. + +1. Group findings by final classification (unsupported, outdated, incorrect, imprecise, speculative, inconclusive, no issues). +2. Format each finding using the standard template (doc claim, verification checklist, code evidence, assessment, recommended action). +3. Provide conservative change suggestions aligned with code reality. +4. Link to specific code artifacts (files, functions, structs, line numbers). +5. Integrate with other analysis findings (e.g., Diataxis compliance). + +**For report formatting template and change suggestion guidelines**, see `references/report_format.md`. + +--- + +## Constraints + +- Complete the verification pass (Stage 2) before reporting any claims. +- Provide code evidence for all documentation consistency claims. +- Code is the source of truth: flag documentation that contradicts code behaviour, not vice versa. +- Do not claim documentation is "unsupported by code" without verification evidence (at least two search strategies with explicit code search and no-match confirmation). +- Do not report false positives. +- Do not prefer "unsupported" when docs are vague or imprecise; use accurate classifications. +- Do not recommend changing code to match docs as the primary action; only documentation should be adjusted to match code reality. + +## Output + +Only verified findings with evidence make it to the final report. Do not include intermediate hypotheses or reasoning. diff --git a/.github/skills/documentation-verify/references/report_format.md b/.github/skills/documentation-verify/references/report_format.md new file mode 100644 index 00000000..de6a96a3 --- /dev/null +++ b/.github/skills/documentation-verify/references/report_format.md @@ -0,0 +1,144 @@ +# Documentation Verification Report Format + +This reference defines how to structure and format the final verification report. + +--- + +## Report Structure + +### 1. Group Findings by Classification + +Organize findings into these categories: + +- **Confirmed unsupported**: Docs describe behaviour or options not present in code +- **Docs outdated**: Code exists but with different values or behaviour than documented +- **Docs incorrect**: Code contradicts doc claim +- **Docs imprecise**: Code behaviour more nuanced than docs suggest +- **Docs speculative**: Describes intended future behaviour (not yet implemented) +- **Inconclusive**: Cannot verify (requires human review) +- **No issues found**: All doc claims backed by code (state this explicitly) + +--- + +## Finding Format Template + +For each verified finding, use this structure: + +````markdown +**Doc Claim**: [File path:line] "[Quoted claim from docs]" + +**Verification Checklist**: +- [ ] Search strategies used: [list at least two strategies] +- [ ] Code location(s) checked: [file paths] +- [ ] Test evidence: [test file/function or "Not found"] +- [ ] Schema/validation: [struct/parser location or "Not found"] + +**Code Evidence**: +- **Expected**: [What docs claim should exist] +- **Found**: [What code actually shows, with file:line references] +- **Assessment**: [Supported | Unsupported | Outdated | Incorrect | Imprecise | Inconclusive] + +**Issue**: [Classification from list above] +- [Brief description of mismatch] + +**Recommended Action**: +- [File path]: [Specific minimal edit to restore correctness] +- Rationale: [Why this edit aligns docs with code] +- Alternative: [If docs are ahead of code, suggest opening an issue or reverting speculative claim] +```` + +--- + +## Conservative Change Suggestions + +When recommending actions, follow these guidelines: + +### For "Docs Outdated" +Update specific values or behaviour descriptions to match current code. + +**Example**: +``` +Recommended Action: +- docs/config.md:42: Change default value from `timeout: 30s` to `timeout: 60s` +- Rationale: Code shows default in config/defaults.go:15 is time.Duration(60 * time.Second) +``` + +### For "Docs Incorrect" +Correct the claim with precise wording from code. + +**Example**: +``` +Recommended Action: +- docs/api.md:78: Change "returns HTTP 200 on success" to "returns HTTP 201 on success" +- Rationale: Handler at handlers/create.go:45 returns http.StatusCreated (201) +``` + +### For "Docs Imprecise" +Add qualifiers, conditions, or edge-case notes. + +**Example**: +``` +Recommended Action: +- docs/cli.md:120: Add note "Only available when --experimental flag is enabled" +- Rationale: Feature gated behind ExperimentalMode check at cmd/feature.go:33 +``` + +### For "Confirmed Unsupported" +Revert or remove unsupported claim. If claim represents intended behaviour, change to future tense and add note. + +**Example**: +``` +Recommended Action: +- docs/features.md:89: Remove claim about auto-retry functionality +- Alternative: If feature is planned, change to "Auto-retry functionality is planned for future release" +``` + +### For "Docs Speculative" +Mark as future or intended, not current behaviour. + +**Example**: +``` +Recommended Action: +- docs/roadmap.md:15: Change "The system supports" to "The system will support (planned)" +- Rationale: No implementation found; appears to be planned feature +``` + +### For "Inconclusive" +Provide specific human review action. + +**Example**: +``` +Recommended Action: +- Request human review: Cannot locate implementation for documented retry logic +- Check: Is this implemented via external library? Search plugin system +``` + +--- + +## Linking to Code Artifacts + +Always reference: +- Specific files with line numbers (e.g., `auth/handler.go:145-167`) +- Function or struct names (e.g., `parseConfig()`, `ServerConfig struct`) +- Test files that exercise the behaviour (e.g., `auth_test.go:TestLoginSuccess`) +- Search commands used (e.g., `grep -r "timeout" config/`) + +--- + +## Report Integration + +- Prioritize code backing findings appropriately (blocking issues for incorrect or unsupported claims) +- Cross-reference with Diataxis compliance findings to identify if inaccuracies stem from category misalignment +- Prepare evidence-based recommendations with code references + +--- + +## Final Output Rule + +**Only verified findings with evidence make it to the final report.** + +Do NOT include: +- Intermediate hypotheses +- Reasoning process +- Unverified claims +- Speculation without code backing diff --git a/.github/skills/documentation-verify/references/verification_procedures.md b/.github/skills/documentation-verify/references/verification_procedures.md new file mode 100644 index 00000000..8f742844 --- /dev/null +++ b/.github/skills/documentation-verify/references/verification_procedures.md @@ -0,0 +1,178 @@ +# Documentation Verification Procedures + +This reference provides comprehensive procedures for verifying documentation accuracy against source code. + +--- + +## Table of Contents + +1. [Discovery Scan Procedures](#discovery-scan-procedures) +2. [Verification Pass Checklist](#verification-pass-checklist) +3. [Evidence Documentation](#evidence-documentation) +4. [Classification Rules](#classification-rules) +5. [False-Positive Prevention](#false-positive-prevention) + +--- + +## Discovery Scan Procedures + +### Step 1: Identify Changed Documentation Claims + +Run `git diff` to list changed documentation files. For each changed file, categorize changes into: + +**Claim Categories:** + +- **Behaviour claims**: Assertions about how the project, commands, or features behave. +- **Options/defaults/constraints**: Documented flags, configuration keys, default values, allowed values, validation rules. +- **Examples**: Code samples, command invocations, YAML/JSON configurations, expected outputs. +- **CLI surface**: Command names, subcommands, flags, help text, output formats. +- **API surface**: REST endpoints, request/response formats, client method signatures, schemas. +- **Error messages**: Documented error text, exit codes, diagnostic output. +- **Terminology/renames/deprecations**: Changed names, deprecated features, migration paths. +- **Interface/component behaviour**: Connection types, interaction mechanics, isolation rules. + +### Step 2: Form Initial Hypotheses + +For each claim, assign a preliminary classification: + +- **Supported**: Claim appears to match code structure (preliminary). +- **Unsupported**: Claim appears inconsistent with code (preliminary). +- **Speculative**: Claim describes future or intended behaviour without code backing. +- **Ambiguous**: Unclear whether claim matches code (needs deeper investigation). +- **Outdated**: Claim may describe previous code behaviour. + +--- + +## Verification Pass Checklist + +**CRITICAL**: Code is the source of truth. Complete verification before reporting any claims. + +### Search Strategies + +Use **at least two distinct search strategies** per claim: + +1. **Direct identifier search**: Search for exact names, keys, constants, struct fields using `grep -r`, `git grep`, ripgrep, or language-specific tools. +2. **Entrypoint tracing**: Follow from CLI, config, or API entrypoint to implementation. +3. **Test evidence search**: Locate tests that exercise the claimed behaviour in test files. +4. **Schema/validation search**: Find parsers, validators, schema generators, struct tags, validation functions. + +### Verification Checklist by Claim Type + +#### Behaviour Claims + +- [ ] Locate implementation code path +- [ ] Verify behaviour matches documented description +- [ ] Check for conditional behaviour (flags, modes, edge cases) +- [ ] Confirm error handling matches docs + +#### Options/Defaults/Constraints + +- [ ] Find struct field or config key definition +- [ ] Extract actual default value from code +- [ ] Find allowed values (enums, validation statements, regex patterns) +- [ ] Verify constraint enforcement + +#### Examples + +- [ ] Confirm example syntax matches actual parser expectations +- [ ] If example shows command output, verify against golden test files or actual execution +- [ ] Confirm field names, indentation, and structure match code expectations +- [ ] Check that referenced flags and options exist in code + +#### CLI Surface + +- [ ] Locate command definition in the CLI framework location +- [ ] Verify command name, aliases, subcommands match +- [ ] Check flag definitions (name, shorthand, type, default, help text) +- [ ] Confirm help text matches command definition +- [ ] Verify output formatting (column headers, sorting) + +#### API Surface + +- [ ] Find route definition +- [ ] Verify HTTP method, path, versioning +- [ ] Check request/response struct definitions +- [ ] Confirm client method signature +- [ ] Verify backward compatibility + +#### Error Messages + +- [ ] Search codebase for exact error text or pattern +- [ ] Verify error is returned in documented scenario +- [ ] Check error message format follows style guide + +#### Terminology/Renames/Deprecations + +- [ ] Search for old name to confirm it is truly deprecated or removed +- [ ] Find deprecation markers, aliases, or migration helpers +- [ ] Check changelog, release notes, or version gating logic +- [ ] Verify new name exists and is used consistently + +--- + +## Evidence Documentation + +### For Claims Supported by Code + +Document: +- File path, function or struct, and line range +- Assessment: `Supported (verified at [file:line])` + +### For Claims Not Supported by Code + +Document: +- Searches performed (at least two strategies with specific search terms) +- What was expected versus what was found +- Assessment: `Unsupported (expected [X], found [Y] at [file:line])` + +### For Inconclusive Claims + +Document: +- Search attempts performed +- What evidence is missing or ambiguous +- Assessment: `Inconclusive (needs human review: [specific check])` + +--- + +## Classification Rules + +Based on verification evidence, reclassify hypotheses using this decision matrix: + +| Original Hypothesis | Verification Outcome | Final Classification | +|---------------------|----------------------|----------------------| +| Unsupported | Found matching code | Retract claim (docs are correct) | +| Unsupported | Found code with different default | Docs outdated (needs value update) | +| Unsupported | No code evidence after thorough search | Confirmed unsupported (docs ahead of code) | +| Supported | Code contradicts doc claim | Docs incorrect (needs correction) | +| Ambiguous | Tests confirm behaviour | Supported (test-backed) | +| Ambiguous | Cannot locate relevant code | Inconclusive (flag for human review) | + +--- + +## False-Positive Prevention + +Apply these rules to avoid false positives: + +1. **Do not claim "unsupported" without documented code search evidence** + - Must have at least two strategies with explicit search terms + +2. **Prefer conservative classifications**: + - Prefer "inconclusive" over "unsupported" when code is complex or evidence is indirect + - Prefer "outdated" over "unsupported" when code exists but with different behaviour or values + - Prefer "imprecise" over "incorrect" when docs are vague but not technically wrong + - Retract claim entirely if verification confirms docs are accurate + +3. **Cross-check documentation coverage**: + - Before claiming "unsupported", verify the entity is not documented elsewhere + - Search `docs/` for related terms, alternative phrasings, synonyms + - If claim is supported elsewhere, classify as "present but undiscoverable" instead + +--- + +## Content Completeness Check + +Before finalizing the report, check that all relevant topics are covered, especially for reference documentation: + +- **CLI**: Verify command-line interface changes are reflected in CLI reference documentation +- **Configuration**: Check that new configuration options are documented in the reference section +- **APIs and schemas**: Validate that API and schema modifications are properly documented