contributing

name	contributing
version	1.0
last_updated	2026-07-20
id	contributing
one_line_purpose	Prepare, validate, and land a testsuite pull request.
entry_point	docs/skills/ci-ops/contributing/SKILL.md
category	ci-ops
mcp_compliance_level	partial
status	active
dependencies	[]
tags	["contributing","pr","merge-queue","review"]
description	How to contribute changes to the testsuite repo. Load when preparing a PR or reviewing contribution mechanics.
metadata	{"type":"pattern","audience":"agents","maturity":"stable"}

Agent Contribution Guide

Load when: you found a bug, gap, or improvement while working in this repo.

This is an agent-first repo — agents MAY file issues and PRs directly. No human gating required.

Nightly CI is gone. PR gates are the only CI signal, and smoke is the standard gate suite for all consumer repos.

Decision: which repo?

Found in	Fix goes in
Feature files, step defs, qecore/dogtail patterns, shared SSH helpers	projectbluefin/testsuite (this repo)
VM specs, CronWorkflows, cluster manifests, infra	projectbluefin/lab

If a fix touches both repos, split into two PRs — one per repo.

When to contribute

Contribute when you encounter any of the following mid-task:

• A skill doc that describes wrong behavior (wrong API, stale path, incorrect command)
• A missing pattern you had to figure out from scratch (add it so the next agent doesn't)
• A new operational gotcha (failed workflow, unexpected infra behavior)
• A step that's broken or uses a deprecated API
• A coverage gap that's now worth tracking

Don't defer. File the PR as part of your current working session.

What to update in the PR

Change	Files to update
New scenario in any suite	Feature file + steps file
Scenario count changes	Run python3 scripts/update_coverage_snapshot.py — it regenerates the suite-map coverage snapshot. Never hand-edit the numbers (that is the merge-conflict root cause). Only hand-edit per-suite Notes prose in the script's SUITE_NOTES if a suite's purpose changed
New unit test file	docs/qa-review.md unit test table
New suite or variant-matrix change	docs/skills/test-authoring/suite-map/SKILL.md variant matrix + docs/runbook.md suite layout table
New step pattern discovered	docs/skills/test-authoring/behave/SKILL.md
New dogtail / GNOME anti-pattern	docs/skills/test-authoring/gnome/SKILL.md