ci: add copilot collections by cmatsuoka · Pull Request #154 · canonical/debcraft

cmatsuoka · 2026-05-08T17:25:50Z

Have you followed the guidelines for contributing?
Have you signed the CLA?
Have you successfully run make lint && make test?

Signed-off-by: Claudio Matsuoka <claudio.matsuoka@canonical.com>

Copilot

Pull request overview

Adds GitHub Copilot “collections” configuration plus a set of Copilot Skills and custom instruction files aimed at standardizing documentation review workflows (build/Diátaxis/structure/accuracy/style) and project-wide Copilot behavior.

Changes:

Added .github/.copilot-collections.yaml to enable Copilot collections (starcraft-docs, common-python).
Introduced documentation review Skills under .github/skills/ (build, Diátaxis, structure, verify, style, and an orchestrating review skill).
Added multiple .github/instructions/*.instructions.md files to guide Copilot behavior for docs, RTD, commenting, and Starcraft docs style/meta.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
.github/.copilot-collections.yaml	Configures Copilot collections and version.
.github/skills/documentation-build/SKILL.md	Defines a docs build-validation skill workflow.
.github/skills/documentation-diataxis/SKILL.md	Defines Diátaxis classification guidance for docs.
.github/skills/documentation-review/SKILL.md	Orchestrates a full documentation review pipeline.
.github/skills/documentation-review/references/doc-review-report-template.md	Template for consolidated documentation review reports.
.github/skills/documentation-structure/SKILL.md	Defines structural auditing steps (metadata/navigation/xrefs).
.github/skills/documentation-style/SKILL.md	Defines style-checking steps and citation requirements.
.github/skills/documentation-style/references/doc-style-guide.md	Adds a project documentation style guide reference.
.github/skills/documentation-verify/SKILL.md	Defines documentation accuracy verification workflow.
.github/skills/documentation-verify/references/report_format.md	Report formatting rules for accuracy verification findings.
.github/skills/documentation-verify/references/verification_procedures.md	Detailed verification procedures and classification rules.
.github/instructions/core-directive.instructions.md	Global Copilot “core directives” for safe changes/tool usage.
.github/instructions/documentation-rtd.instructions.md	RTD-specific docs testing/linking/toctree guidance.
.github/instructions/documentation.instructions.md	General documentation guidance for Copilot.
.github/instructions/instructions.instructions.md	Guidance on writing and structuring instruction files.
.github/instructions/python-code-commenting.instructions.md	Guidance for writing minimal/high-value code comments.
.github/instructions/starcraft-docs-meta.instructions.md	Starcraft docs meta-description guidance for docs pages.
.github/instructions/starcraft-docs-style.instructions.md	Starcraft documentation style guide content for docs pages.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@@ -0,0 +1,505 @@
+---


@@ -0,0 +1,80 @@
+---


+## 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: `'**'`


+
+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.


cmatsuoka · 2026-05-08T20:28:21Z

+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.


We should rename the directories instead?

+- 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).


+├── tutorial/          # Step-by-step learning paths
+├── how-to/            # Task-oriented guides


+**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`
+


+
+1. **Identify intended category**: Determine the declared category
+   based on directory location
+   (`tutorial/`, `how-to/`, `explanation/`, `reference/`)


+
+    Confirm the file is located in the directory matching its intended
+    Diataxis category
+    (for example, tutorials in `tutorial/`, how-to guides in `how-to/`).


mr-cal

I see your commit that reformatted the markdown files.

I'd recommend updating the precommit and makefile to ignore these files (example from snapcraft).

Otherwise, your formatting will be undone the next time copilot-collections is updated.

cmatsuoka force-pushed the ci/add-copilot-collections branch from 945cc7e to d623be1 Compare May 8, 2026 17:31

ci: add copilot collections

bc414fd

Signed-off-by: Claudio Matsuoka <claudio.matsuoka@canonical.com>

cmatsuoka force-pushed the ci/add-copilot-collections branch from d623be1 to bc414fd Compare May 8, 2026 17:38

chore: reformat instructions and skills

4212743

Signed-off-by: Claudio Matsuoka <claudio.matsuoka@canonical.com>

cmatsuoka requested review from lengau and mr-cal May 8, 2026 20:14

cmatsuoka marked this pull request as ready for review May 8, 2026 20:14

cmatsuoka requested a review from Copilot May 8, 2026 20:14

Copilot started reviewing on behalf of cmatsuoka May 8, 2026 20:15 View session

Copilot AI reviewed May 8, 2026

View reviewed changes

lengau approved these changes May 8, 2026

View reviewed changes

mr-cal approved these changes May 19, 2026

View reviewed changes

Navigation Menu

Uh oh!

ci: add copilot collections - #154

ci: add copilot collections#154
cmatsuoka wants to merge 2 commits into
canonical:mainfrom
cmatsuoka:ci/add-copilot-collections

cmatsuoka commented May 8, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

cmatsuoka May 8, 2026

Uh oh!

mr-cal left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants


		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.

		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.

		├── tutorial/ # Step-by-step learning paths
		├── how-to/ # Task-oriented guides

Uh oh!

Conversation

cmatsuoka commented May 8, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

cmatsuoka May 8, 2026

Choose a reason for hiding this comment

Uh oh!

mr-cal left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants