Maintain the project¶

This maintainer guide combines task-oriented release and documentation procedures with reference information about automation and repository tooling. Use it for work that sits outside the day-to-day contribution flow.

Releases¶

See the release notes for more information on the general approach. The steps to produce a Workshop release are as follows.

Build the snaps locally¶

Snapcraft is used to build, package, and publish workshop snaps. All these processes run in a self-launched LXD container. To run the build, install snapcraft and lxd using snap:

$ sudo snap install --classic snapcraft
$ sudo snap install --channel=6/stable lxd

Add the current user to the lxd group to give permission to access its resources:

$ sudo usermod -a -G lxd $USER

Log out and reopen your user session for the new group to become active, then initialize LXD:

$ lxd init

Publish the release¶

Here’s the publishing checklist to follow:

Merge and close the outstanding pull requests from the release scope
Make sure the unit, integration, and documentation tests are green; see Contribute to development and Contribute to this documentation for details
Update the documentation; see Release documentation for the full checklist
Create and push a new release tag with git, using semantic versioning
Run the release workflow on GitHub; this builds and publishes release snaps for the supported architectures, creates a GitHub release, and adds a pull request to update the CLI reference
Generate the change log on GitHub

Release documentation¶

At every release, remember to:

Merge the auto-generated CLI reference pull request.
Bump the snap revision used across the docs.
Refresh the three schema files under docs/reference/definition-files/.

Regenerate schema-sdk.json and schema-sdkcraft.json in a local SDKcraft repository checkout and copy the outputs over:
```
$ cd <PATH-TO-SDKCRAFT-CHECKOUT>
$ uv run python sdkcraft/models/metadata.py
$ uv run python sdkcraft/models/project.py
$ cp schema-sdk.json schema-sdkcraft.json \
     <PATH-TO-WORKSHOP-CHECKOUT>/docs/reference/definition-files/
```
The Workshop schema.json is hand-audited against internal/workshop/workshop_file.go.
Update the release notes with relevant details, following the established format; for an SDKcraft release, update the respective section in the same manner.
Copy the release notes to the documentation under docs/release-notes/ and update the latest version in docs/release-notes/index.rst; the recent version lists should contain versions from the last 6 months.
Refresh the coverage map by running the .github/workflows/doc-cover.yaml workflow and merging the resulting pull request.
Copy the auto-generated SDKcraft CLI reference from the SDKcraft repository to docs/reference/cli/ as sdkcraft*.rst, making sure the updated documentation builds properly.

CLI reference generation¶

The command-line reference for Workshop is produced directly from the Cobra command tree:

$ go run ./cmd/workshop generate-docs

The helper in cmd/workshop/gendocs.go uses the Gencodo Go module to convert the command metadata into *.rst files with templates. In particular, this is used during the release workflow.

The command-line reference for SDKcraft can be generated in the SDKcraft repository. Run gendocs.py there to generate the files. The current implementation relies on craft-application and doesn’t fully integrate with Workshop documentation yet.

CI/CD¶

Multiple GitHub Actions workflows, defined in the .github/workflows/ directory, automate testing, building, documentation, and release processes.

Some of these workflows come from the starter pack (marked SP), while others are custom-made for Workshop’s needs.

Documentation workflows:

Workflow	Purpose
`automatic-doc-checks.yml` (SP)	Build the documentation and fail on Sphinx warnings.
`doc-cover.yaml`	Generate and update the documentation coverage map.
`doc-update-sdk-schema.yml`	Update SDK schema files from the SDKcraft repository.
`fix-redirected-links.yml`	Update selected redirecting documentation links and open a pull request.
`markdown-style-checks.yml` (SP)	Lint Markdown documentation files.
`update-sphinx-stack.yaml`	Update Sphinx Stack files and documentation dependencies weekly and on demand.

Code quality and testing workflows:

Workflow	Purpose
`cover.yaml`	Orchestrates `spread.yaml` and `unit-tests.yaml`; aggregates coverage reports.
`fixup.yaml`	Check for fixup and squash commits in pull requests.
`lint.yaml`	Run golangci-lint on Go code.
`scanning.yml`	Scan for known security vulnerabilities using Trivy.
`spread.yaml`	Run end-to-end tests with Spread (reusable workflow).
`staging.yaml`	Prevent staged test SDKs from being merged.
`unit-tests.yaml`	Run Go unit tests and check for race conditions (reusable workflow).
`zizmor.yaml`	Audit GitHub Actions workflows for security issues.

Build and release workflows:

Workflow	Purpose
`build-deps.yaml`	Build and cache the Workshop snap (reusable workflow).
`lxd-candidate-check.yaml`	Test Workshop against the LXD candidate channel daily; uses `build-deps.yaml`.
`release.yaml`	Build release snaps for ARM64 and X64; create GitHub release and trigger CLI docs update PR.

Copilot configuration¶

The repository includes configurations to help GitHub Copilot provide assistance; these are located in the .github/ directory and include general instructions as well as custom agents and reusable skills for specific tasks.

Copilot instructions¶

The .github/copilot-instructions.md file provides general project context to GitHub Copilot.

Also, there are documentation- and code-specific instructions in .github/docs.instructions.md and .github/go.instructions.md, tailored to guide Copilot when assisting with documentation and Go code tasks, respectively.

Agents and skills¶

The .github/agents/ subdirectory contains custom agent prompts for review and maintenance tasks:

code-review.agent.md: A code review specialist that enforces commit message standards, coding conventions, and error handling patterns, referencing the development contribution guide and the coding style guide.
doc-schema-update.agent.md: A specialized agent for reconciling the JSON schema in docs/reference/definition-files/schema.json with the validation logic in internal/workshop/workshop_file.go.

The .github/skills/ subdirectory contains reusable skills. The .github/skills/documentation-review/SKILL.md skill orchestrates build validation, content analysis, accuracy verification, structure checks, and style review using the documentation contribution guide and the documentation style guide.

These agents and skills provide structured, actionable feedback and help maintain consistency across contributions.