<a id="contributing-maintenance"></a>

# 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](https://ubuntu.com/workshop/docs//release-notes/index.md#release-notes)
for more information on the general approach.
The steps to produce a **Workshop** release are as follows.

### Build the snaps locally

[Snapcraft](https://documentation.ubuntu.com/snapcraft/stable/)
is used to build, package, and publish **workshop** snaps.
All these processes run in a self-launched
[LXD](https://documentation.ubuntu.com/lxd/latest/) container.
To run the build,
install **snapcraft** and **lxd** using **snap**:

```console
$ 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:

```console
$ sudo usermod -a -G lxd $USER
```

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

```console
$ 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](https://ubuntu.com/workshop/docs//contributing/development.md#contributing-development) and [Contribute to this documentation](https://ubuntu.com/workshop/docs//contributing/documentation.md#contributing-documentation) for details
- Update the documentation;
  see [Release documentation](#contributing-doc-release) for the full checklist
- Create and push a new release tag with **git**,
  using [semantic versioning](https://semver.org/)
- Run the [release workflow](https://github.com/canonical/workshop/actions/workflows/release.yaml)
  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](https://ubuntu.com/workshop/docs//reference/cli/workshop.md#ref-workshop-cli)
- Generate the
  [change log](https://github.com/canonical/workshop/releases/new)
  on GitHub

<a id="contributing-doc-release"></a>

## 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:
  ```console
  $ 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](https://github.com/canonical/workshop/releases)
  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](https://github.com/canonical/workshop/blob/main/docs/coverage.md)
  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](https://github.com/canonical/sdkcraft)
  to `docs/reference/cli/` as `sdkcraft*.rst`,
  making sure the updated documentation builds properly.

<a id="contributing-doc-generation"></a>

## CLI reference generation

The [command-line reference](https://ubuntu.com/workshop/docs//reference/cli/workshop.md#ref-workshop-cli) for **Workshop**
is produced directly from the Cobra command tree:

```console
$ go run ./cmd/workshop generate-docs
```

The helper in `cmd/workshop/gendocs.go`
uses the [Gencodo](https://github.com/canonical/gencodo) Go module
to convert the command metadata into `*.rst` files with templates.
In particular, this is used during the
[release workflow](#contributing-cicd).

The [command-line reference](https://ubuntu.com/workshop/docs//reference/cli/sdkcraft.md#ref-sdkcraft-cli) for **SDKcraft**
can be generated in the **SDKcraft** repository.
Run `gendocs.py` there to generate the files.
The current implementation relies on
[craft-application](https://github.com/canonical/craft-application/)
and doesn’t fully integrate with **Workshop** documentation yet.

<a id="contributing-cicd"></a>

## CI/CD

Multiple
[GitHub Actions](https://docs.github.com/en/actions/get-started/understand-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](https://ubuntu.com/workshop/docs//contributing/documentation.md#contributing-doc-structure) (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<br/>and on demand. |

Code quality and testing workflows:

| Workflow          | Purpose                                                                            |
|-------------------|------------------------------------------------------------------------------------|
| `cover.yaml`      | Orchestrates `spread.yaml` and `unit-tests.yaml`;<br/>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;<br/>uses `build-deps.yaml`.           |
| `release.yaml`             | Build release snaps for ARM64 and X64;<br/>create GitHub release and trigger CLI docs update PR. |

<a id="contributing-copilot"></a>

## 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](https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/create-custom-agents)
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](https://ubuntu.com/workshop/docs//contributing/development.md#contributing-development)
  and the [coding style guide](https://ubuntu.com/workshop/docs//coding-style-guide.md#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](https://ubuntu.com/workshop/docs//contributing/documentation.md#contributing-documentation)
and the [documentation style guide](https://ubuntu.com/workshop/docs//doc-style-guide.md#doc-style-guide).

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