101 lines
4.5 KiB
Markdown
101 lines
4.5 KiB
Markdown
---
|
|
name: dot-ai-changelog-fragment
|
|
description: Create changelog fragment for release notes. Invoke during /prd-done workflow during the first push to the PR.
|
|
user-invocable: true
|
|
---
|
|
|
|
# Create Changelog Fragment
|
|
|
|
Create a towncrier changelog fragment for release notes when completing PRD work. This should be included in the PR so the fragment is reviewed along with the code changes.
|
|
|
|
## Workflow
|
|
|
|
### Step 1: Identify the PRD
|
|
|
|
If not already known from context, ask: "Which PRD should I create release notes for?"
|
|
|
|
Look for:
|
|
- PRD mentioned in recent conversation
|
|
- PRD referenced in current branch name (e.g., `feature/prd-320-*`)
|
|
- PRD file path provided by user
|
|
|
|
### Step 2: Read the PRD Thoroughly
|
|
|
|
Read the entire PRD file to extract:
|
|
- **Problem Statement**: What user pain point was solved, why it mattered
|
|
- **Solution Overview**: What the feature does, how it works
|
|
- **User Impact**: Specific benefits, what users can now do
|
|
- **Key Capabilities**: Individual features, options, or modes added
|
|
- **Technical Details**: Configuration options, environment variables, commands
|
|
- **Documentation Updates**: Which docs were added or updated (check Milestones section)
|
|
|
|
### Step 3: Determine Fragment Type
|
|
|
|
Read `pyproject.toml` to see the available fragment types. Each `[[tool.towncrier.type]]` section has:
|
|
- A comment above it describing when to use that type
|
|
- A `directory` field (the type identifier used in the filename, e.g., `feature` for `.feature.md`)
|
|
|
|
Choose the type that best matches the PRD based on those descriptions.
|
|
|
|
### Step 4: Write the Fragment
|
|
|
|
Create file: `changelog.d/[issue-id].[type].md`
|
|
|
|
**IMPORTANT: Use flat structure, NOT subdirectories!**
|
|
- ✅ Correct: `changelog.d/329.feature.md`
|
|
- ❌ Wrong: `changelog.d/feature/329.md`
|
|
|
|
**Naming convention:**
|
|
- `issue-id`: GitHub issue number from PRD (e.g., `320`)
|
|
- `type`: Type identifier from step 3 (e.g., `feature`, `bugfix`, `misc`)
|
|
|
|
**Content format:**
|
|
```markdown
|
|
## [Feature Title]
|
|
|
|
[Opening sentence: What this feature is and the problem it solves]
|
|
|
|
[Key capabilities paragraph: Specific things users can now do, with concrete examples]
|
|
|
|
[Configuration/usage paragraph if applicable: How to enable or use the feature]
|
|
|
|
[Documentation link if docs were updated]
|
|
```
|
|
|
|
**Documentation links:**
|
|
If the PRD includes documentation updates, link to the relevant page on devopstoolkit.ai. The URL pattern is:
|
|
- `https://devopstoolkit.ai/docs/{project}/{path}`
|
|
- Where `{project}` is: `mcp` (dot-ai), `controller` (dot-ai-controller), `ui` (dot-ai-ui), or `stack` (dot-ai-stack)
|
|
- And `{path}` maps from the docs folder (e.g., `docs/guides/mcp-recommendation-guide.md` → `guides/mcp-recommendation-guide`)
|
|
|
|
**Example: `changelog.d/142.feature.md`**
|
|
```markdown
|
|
## Multi-Cluster Management
|
|
|
|
Manage multiple Kubernetes clusters from a single dot-ai instance. Previously, each cluster required its own dot-ai deployment, making it difficult to compare configurations or apply consistent patterns across environments.
|
|
|
|
The `query` tool now accepts a `--cluster` flag to target specific clusters, and results indicate which cluster each resource belongs to. The `recommend` tool can generate manifests targeting different clusters with environment-specific customizations. Cross-cluster searches let you find resources across all connected clusters simultaneously—useful for tracking down where a particular workload is deployed. Cluster health aggregation shows a unified view of all clusters in the `version` output.
|
|
|
|
Configure additional clusters by adding kubeconfig contexts to `ADDITIONAL_KUBECONFIGS` (comma-separated paths). Each context becomes available as a cluster target. The default cluster remains the current kubeconfig context when no `--cluster` flag is specified.
|
|
|
|
See the [Multi-Cluster Setup Guide](https://devopstoolkit.ai/docs/mcp/setup/multi-cluster-setup) for configuration details and examples.
|
|
```
|
|
|
|
### Step 5: Confirm Creation
|
|
|
|
Show the user:
|
|
1. The fragment file path created
|
|
2. The content written
|
|
3. Reminder to commit and push with the PR
|
|
|
|
## Guidelines
|
|
|
|
- **User-focused**: Describe what users gain, not implementation details
|
|
- **Specific**: Include concrete examples of what each capability does
|
|
- **Complete**: Cover all major features added, not just the headline
|
|
- **Present tense**: "Tools now return..." not "Added support for..."
|
|
- **No diary style**: "Multi-Cluster Management" not "Added multi-cluster support"
|
|
- **Include configuration**: Mention environment variables, commands, or setup steps
|
|
- **Link to docs**: If PRD updated documentation, link to the specific page on devopstoolkit.ai
|
|
|