documentation
/documentation
Feature documentation and release notes patterns. Use when documenting changes, writing PR descriptions, or preparing releases.
- Author
- comet-ml ↗
- Repository
- opik ↗
- Licence
- Apache-2.0
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
What it does and when to use it
Feature documentation and release notes patterns. Use when documenting changes, writing PR descriptions, or preparing releases.
Original author description
Feature documentation and release notes patterns. Use when documenting changes, writing PR descriptions, or preparing releases.
How it works
- PR Description
- Changelog Entry
- Feature Documentation
- Key Files
- Changelog Routing Rules
- Images in documentation
- Internationalized READMEs
- Style
SKILL.md preview
--- name: documentation description: Feature documentation and release notes patterns. Use when documenting changes, writing PR descriptions, or preparing releases. --- # Documentation ## PR Description Use the repository template at `.github/pull_request_template.md` — read the FULL file before drafting (the required sections continue past the first screen). CI (`.github/workflows/pr-lint.yml`) fails any PR whose description is missing one of these exact headings: - `## Details` - `## Change checklist` - `## Issues` - `## Testing` - `## Documentation` Also fill in the template's `## AI-WATERMARK` section (yes/no; if yes: Tools, Model(s), Scope, Human verification). Never invent a different structure such as `## Summary` / `## Test Plan`. A section that does not apply gets `N/A` — never delete a heading. ### `## Details` — style Write what changes for a user. A reviewer reads the diff for the code; this section tells them what is different when they use the product. - **Short.** Most PRs need 3–10 bullets. If it runs longer, the section is doing the diff's job — cut it. - **Bullets, not prose paragraphs.** One behavior per bullet. Nest one level for sub-cases. - **Authoritative.** State what happens: "The run is scored once." Not "This should now mean that the run will be scored once." - **No fluff.** No motivation paragraph, no "this PR …", no approach summary, no benefits list, no restating the diff. - **Observable behavior first.** What the UI shows, what the API returns, what gets scored, stored or logged. Name a class, method or file only when the behavior makes no sense without it. Pick the shape that fits the change — do not force one: - **Before / After bullet lists** when a behavior changed and the contrast is the point. - **A flat bullet list** for a new capability, where there is no "before". - **One or two lines** when users cannot see the change (refactor, dependency bump) — say what is unchanged and what improved, then stop. ## Changelog Entry ```markdown ### [VERSION] - [DATE] #### New Features - **Feature Name**: Brief description #### Improvements - **Improvement**: What changed and why #### Bug Fixes - **Fix**: What was broken (#issue) #### Breaking Changes - **Change**: What breaks, migration steps ``` ## Feature Documentation When documenting a feature, cover: **User Impact** - What capability does this add? - How do users access it? **Technical Changes** - API changes (endpoints, params) - SDK changes (new methods) - Database migrations - Config changes **Breaking Changes** (if any) - What breaks - Migration steps ## Key Files - `apps/opik-documentation/documentation/fern/docs-v2/self-host/changelog.mdx` - Self-hosted deployment changelog (breaking/critical changes only; the former repo-root `CHANGELOG.md` was removed) - `apps/opik-documentation/documentation/fern/docs-v2/changelog/` - Main product docs changelog entries (dated `.mdx` files) - `apps/opik-documentation/documentation/fern/docs-v2/development/optimization-runs/changelog.mdx` - Agent Optimizer release changelog - `apps/opik-documentation/documentation/fern/docs.yml` - Docs routing/navigation source of truth for changelog surfaces - `.github/release-drafter.yml` - Release template ## Changelog Routing Rules - Pick the changelog target by scope; do not default everything to one surface. - Use `apps/opik-documentation/documentation/fern/docs-v2/self-host/changelog.mdx` only for self-hosted deployment breaking/critical/security-impacting notes. - Use `apps/opik-documentation/documentation/fern/docs-v2/changelog/*.mdx` for general Opik product release notes shown in `/docs/opik/changelog`. - Use `apps/opik-documentation/documentation/fern/docs-v2/development/optimization-runs/changelog.mdx` for Agent Optimizer version updates (for example `sdks/opik_optimizer` releases like `3.1.0`). - Liquibase `changelog.xml` files are migration manifests, not user-facing release-note changelogs. - If unsure where an entry belongs, confirm the surface from `apps/opik-documentation/documentation/fern/docs.yml` before editing. ## Images in documentation - **Use `fern/img`** for documentation images (e.g. `apps/opik-documentation/documentation/fern/img/...`). - **Do not use `static/img`** for new assets; it is a legacy folder used by external integrations and cannot be deleted. - Reference images in docs as `/img/...` (e.g. `/img/tracing/openai_integration.png`). - In repos that define `docs.yaml`/`docs.yml`, treat that file as the routing source of truth; do not assume URLs mirror directory layout. ## Internationalized READMEs Non-English README files (`readme_CN.md`, `readme_ES.md`, `readme_FR.md`, `readme_DE.md`) are AI machine-translated from the English `README.md`. - Each non-English README must have a notice at the top (as a blockquote) warning that the file is AI-translated and welcoming improvements. - When the English README is updated with significant content changes, re-translate the affected non-English READMEs using AI and update accordingly. - Do not manually edit translated READMEs for content changes; update the English source and re-translate. ## Style - User perspective, not implementation details - Specific (version numbers, dates) - Code examples for API/SDK changes - Concise - link to docs, don't duplicate
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · comet-ml/opik | 100 | Apache-2.0 |
| software-combined/SC_AI | 100 | Apache-2.0 |
| DaveSkender/Stock.Indicators | 100 | Apache-2.0 |
| mcouthon/agents | 100 | MIT |
| YLfjuk/deltafold | 100 | MIT |
| runwield/runwield | 100 | MIT |
| anthropics/knowledge-work-plugins | 100 | Apache-2.0 |
| luocfprime/labtasker | 100 | Apache-2.0 |
| oborchers/fractional-cto | 100 | MIT |
Identical content appears in 1 other GitHub folders. We show one copy with the highest score.
Database snapshot: 13.11.2026 · package version cd2e023b2c88 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100draft-release-notes
Compare NeMo Relay release branches and draft or update the documentation-site release notes. Use when preparing a release-notes update under docs/about-nemo-relay/release-notes, reviewing release-to-release changes, or gathering evidence for a current release summary. - 90dev10x:release-notes
Generate JTBD-driven release notes from git commits between releases. Playbook-powered workflow with configurable ticket patterns, output targets, and categories. TRIGGER when: preparing a release and need to generate changelog or release notes from commit history. DO NOT… - 100changelog-generator
Generate release notes and changelogs from git commits, feature lists, or project updates. Use when a user asks to generate a changelog, create release notes, summarize recent changes, draft a CHANGELOG entry, or prepare release documentation from git history. - 100writing-release-notes
Use when preparing, refreshing, backfilling, or redrafting a release-notes page under docs/releases/ before opening a normal review pull request. - 100repository-writing-style
Apply the repository's writing style whenever creating or substantially editing Markdown documentation, GitHub issues, pull request descriptions, review notes, release notes, changelogs, or other contributor-facing prose. - 100technical-writing
Create architectural decision records (ADRs), system documentation, API documentation, and operational runbooks. Use when capturing design decisions, documenting system architecture, creating API references, or writing operational procedures.