Skip to content

Commit 8535cf7

Browse files
committed
docs(copilot): add Conventional Commits standards and scope guidance
- Document Conventional Commits 1.0.0 specification from Context7 - Add required types (feat, fix) and recommended types - Define scopes as functional/logical areas, not physical projects - Include common scopes: core, ui, logging, config, build, ci, tests, etc. - Provide examples and guidance on when to use/omit scopes - Document breaking change notation and footer conventions - Cross-reference with Serena memory for consistency
1 parent 715a2f0 commit 8535cf7

File tree

2 files changed

+150
-102
lines changed

2 files changed

+150
-102
lines changed

.github/copilot-instructions.md

Lines changed: 144 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -259,6 +259,149 @@ dotnet test --filter "FullyQualifiedName~BatchConfigurationTests"
259259
- **External tools**: mkvpropedit is executed with controlled arguments; validate user input before passing to command line
260260
- **File operations**: All file modifications require explicit user action (no automatic writes on scan)
261261

262+
## Commit Message Standards
263+
264+
**Copilot MUST follow [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/) specification when generating commit messages.**
265+
266+
### Format
267+
```
268+
<type>[optional scope]: <description>
269+
270+
[optional body]
271+
272+
[optional footer(s)]
273+
```
274+
275+
### Required Types
276+
- `feat:` - A new feature (correlates with MINOR in SemVer)
277+
- `fix:` - A bug fix (correlates with PATCH in SemVer)
278+
279+
### Recommended Types
280+
Additional types from @commitlint/config-conventional (Angular convention):
281+
- `build:` - Changes to build system or dependencies
282+
- `chore:` - Maintenance tasks
283+
- `ci:` - CI/CD configuration changes
284+
- `docs:` - Documentation changes
285+
- `style:` - Code style/formatting changes (no functional changes)
286+
- `refactor:` - Code refactoring without behavior change
287+
- `perf:` - Performance improvements
288+
- `test:` - Adding or updating tests
289+
- `revert:` - Reverting a previous commit
290+
291+
### Scope (Optional)
292+
Scopes represent **what the change is about** (functional/logical areas), not just physical project locations.
293+
294+
**Common scopes used in this codebase:**
295+
296+
*Project layers:*
297+
- `core` - Core library logic (MatroskaBatchFlow.Core)
298+
- `ui` - Views, XAML, and presentation components
299+
- `vm` - ViewModels and MVVM patterns
300+
301+
*Domain-specific:*
302+
- `validation` - Validation system (rules, engine, strictness modes)
303+
- `processing` - File processing pipeline and batch operations
304+
- `tracks` - Track configuration and track-level logic
305+
- `mkvtools` - mkvpropedit/MediaInfo integration
306+
307+
*Infrastructure:*
308+
- `config` - Configuration and settings
309+
- `logging` - Logging system
310+
- `di` - Dependency injection and service registration
311+
- `nav` - Navigation system
312+
313+
*Tooling:*
314+
- `deps` - Package dependencies
315+
- `dev` - Development tooling
316+
317+
*Documentation:*
318+
- `instructions` - AI assistant instructions (copilot-instructions.md, Serena memories)
319+
320+
*Release:*
321+
- `version` - Version management
322+
- `release` - Release and publishing
323+
324+
> **Note:** `build`, `ci`, `docs`, and `test` are commit **types**, not scopes. Use them as types (e.g., `build: update project files`, `test: add validation tests`).
325+
326+
**When to use a scope:**
327+
- Changes focus on a specific functional area or component
328+
- Examples: `feat(logging): add structured logging`, `fix(config): handle invalid JSON`, `refactor(ui): simplify navigation`
329+
330+
**When to omit the scope:**
331+
- Changes are truly repository-wide or don't fit a single category
332+
- Examples: `chore: update all dependencies`, `docs: update README`
333+
334+
**Multiple scopes:**
335+
- Use comma-separated scopes when changes span multiple areas: `refactor(core,ui): redesign batch processing`
336+
337+
**Expanding scopes:**
338+
- The scopes above are common examples, not an exhaustive list
339+
- Create new scopes when needed for clarity (e.g., `feat(dialogs): add confirmation dialog`)
340+
341+
### Breaking Changes
342+
- **Option 1**: Add `!` after type/scope: `feat(core)!: redesign batch processing API`
343+
- **Option 2**: Use footer: `BREAKING CHANGE: description` (MUST be uppercase)
344+
- Breaking changes correlate with MAJOR in SemVer
345+
346+
### Body (Optional)
347+
- Provide additional context after a blank line
348+
- Free-form text, may contain multiple paragraphs
349+
- **Project preference**: Use bullet points for clarity
350+
351+
### Footer(s) (Optional)
352+
Footers follow git trailer format (token: value or token #value):
353+
- `BREAKING CHANGE: <description>` - Breaking change details
354+
- `Refs: #123` - Reference issues
355+
- `Closes: #123` or `Fixes: #123` or `Resolves: #123` - Close issues
356+
- `Reviewed-by:`, `Acked-by:`, `See-also:` - Other standard git trailers
357+
358+
### Examples
359+
360+
**Simple feature:**
361+
```
362+
feat(core): add subtitle track reordering support
363+
```
364+
365+
**Bug fix with body and footer:**
366+
```
367+
fix(ui): prevent UI freeze during large batch operations
368+
369+
- Move batch processing to background thread
370+
- Add progress reporting with cancellation support
371+
- Update MainViewModel to marshal UI updates
372+
373+
Closes: #89
374+
```
375+
376+
**Breaking change with scope:**
377+
```
378+
feat(core)!: redesign track configuration API
379+
380+
- Replace TrackConfiguration with immutable TrackInfo
381+
- Update all track ViewModels to use new API
382+
- Migration guide added to docs/migration.md
383+
384+
BREAKING CHANGE: TrackConfiguration class removed, use TrackInfo instead
385+
Refs: #125
386+
```
387+
388+
**Documentation update:**
389+
```
390+
docs: update README with mkvpropedit installation guide
391+
392+
Refs: #42
393+
```
394+
395+
### Important Rules
396+
- Type and description are REQUIRED
397+
- Description MUST immediately follow the colon and space
398+
- Scope MUST be a noun in parentheses if provided
399+
- BREAKING CHANGE footer MUST be uppercase
400+
- Breaking changes can use `!` in prefix OR footer (or both)
401+
- Tokens other than BREAKING CHANGE are case-insensitive
402+
403+
> **Cross-reference**: Detailed Conventional Commits standards are also in Serena's memory (`.serena/memories/task_completion_checklist.md`). Keep both locations synchronized.
404+
262405
## **CRITICAL: Always Use Serena First (#serena MCP server)**
263406

264407
**Serena is a semantic code analysis toolkit that provides IDE-like capabilities to AI assistants. It's designed for:**
@@ -361,7 +504,7 @@ dotnet test --filter "FullyQualifiedName~BatchConfigurationTests"
361504
2. Update relevant sections in this file
362505
3. Update Serena memories to match
363506
4. Update "Last Updated" date at the top
364-
5. Commit both code changes and instruction updates together
507+
5. Commit both code changes and instruction updates together using Conventional Commits format
365508

366509
**Review cadence:**
367510
- Minor updates: As needed when patterns change

.serena/memories/task_completion_checklist.md

Lines changed: 6 additions & 101 deletions
Original file line numberDiff line numberDiff line change
@@ -138,109 +138,14 @@ git commit -m @"
138138
```
139139

140140
### Commit Message Format
141-
Follow the **[Conventional Commits 1.0.0](https://www.conventionalcommits.org/)** specification.
142141

143-
**Structure:**
144-
```
145-
<type>[optional scope]: <description>
146-
147-
[optional body]
148-
149-
[optional footer(s)]
150-
```
151-
152-
**Required Elements:**
153-
- **type**: Noun describing the change (e.g., `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`)
154-
- `feat`: New feature (correlates with MINOR in SemVer)
155-
- `fix`: Bug fix (correlates with PATCH in SemVer)
156-
- **description**: Short summary immediately following `: ` (imperative mood, e.g., "add feature" not "adds feature")
157-
158-
**Optional Elements:**
159-
- **scope**: Section of codebase in parentheses (e.g., `core`, `uno`, `cli`, `tests`)
160-
- **!**: Appended after type/scope to indicate breaking change
161-
- **body**: Additional context, begins one blank line after description, free-form
162-
- *Project preference:* Use bullet points when listing multiple changes (not required, but preferred for clarity)
163-
- **footer(s)**: Metadata following git trailer format
164-
- `Refs: #123` - References issue(s) without closing it
165-
- `Closes: #123` (or `Fixes:`, `Resolves:`) - References and automatically closes issue(s) on GitHub
166-
- Other footers: `See-also: #456`
167-
168-
**Breaking Changes:**
169-
MUST be indicated by either (or both):
170-
- Appending `!` immediately before `:` (e.g., `feat!:` or `feat(api)!:`)
171-
- Footer with `BREAKING CHANGE: <description>` (MUST be uppercase)
172-
173-
Breaking changes correlate with MAJOR in SemVer and can be part of any commit type.
174-
175-
**Examples:**
176-
177-
Commit with description only:
178-
```
179-
docs: correct spelling of CHANGELOG
180-
```
181-
182-
Commit with scope:
183-
```
184-
feat(lang): add Polish language
185-
```
186-
187-
Commit with body:
188-
```
189-
fix: prevent racing of requests
190-
191-
Introduce a request id and a reference to latest request. Dismiss
192-
incoming responses other than from latest request.
193-
```
194-
195-
Commit with bulleted body (project preference):
196-
```
197-
feat(cli): add recursive folder processing
142+
Follow **[Conventional Commits 1.0.0](https://www.conventionalcommits.org/)** specification.
198143

199-
- Process nested folders in batch jobs
200-
- Preserve original file timestamps
201-
- Skip hidden/system files automatically
202-
```
203-
204-
Breaking change with `!`:
205-
```
206-
feat(api)!: send an email to the customer when a product is shipped
207-
```
208-
209-
Breaking change with footer:
210-
```
211-
feat: allow provided config object to extend other configs
212-
213-
BREAKING CHANGE: `extends` key in config file is now used for extending other config files
214-
```
215-
216-
Multiple footers:
217-
```
218-
fix: prevent racing of requests
219-
220-
Introduce a request id and a reference to latest request. Dismiss
221-
incoming responses other than from latest request.
222-
223-
Refs: #123
224-
```
225-
226-
Closing an issue:
227-
```
228-
fix(core): handle empty MKV metadata gracefully
229-
230-
- Return default values for missing track info
231-
- Log warning instead of throwing exception
232-
- Add unit tests for edge cases
233-
234-
Refs: #38
235-
Closes: #42
236-
```
237-
238-
Revert commit:
239-
```
240-
revert: let us never again speak of the noodle incident
241-
242-
Refs: 676104e, a215868
243-
```
144+
See `.github/copilot-instructions.md`**Commit Message Standards** section for:
145+
- Required and recommended types
146+
- Codebase-specific scopes
147+
- Breaking change conventions
148+
- Examples
244149

245150
## 8. Clean Up
246151

0 commit comments

Comments
 (0)