Repository Documentation Updates

This skill helps update core repository documentation files before committing changes or creating releases.

When to Use This Skill

Use this skill when:

• •Preparing to commit changes and need to update documentation
• •Creating a release and need to update CHANGELOG
• •Documentation is out of sync with code changes
• •Need to add or update core repository files (README, CHANGELOG, LICENSE, CONTRIBUTING)

Core Documentation Files

README.md

Primary documentation file covering:

• •Project overview and purpose
• •Setup and installation instructions
• •Basic usage examples
• •Development guidelines
• •Links to additional documentation

Common updates:

• •Add new features or capabilities
• •Update installation steps
• •Revise configuration instructions
• •Add or update examples

CHANGELOG.md

Chronological record of changes following Keep a Changelog format.

Structure:

# Changelog

## [Unreleased]
### Added
- New features not yet released

### Changed
- Changes to existing functionality

### Fixed
- Bug fixes

## [X.Y.Z] - YYYY-MM-DD
### Added
- Feature descriptions

### Changed
- Modification descriptions

### Fixed
- Bug fix descriptions

Common updates:

• •Move items from Unreleased to new version section
• •Add new version entry with date
• •Document new features, changes, and fixes
• •Add version comparison links at bottom

LICENSE

Legal terms for code usage and distribution.

Common updates:

• •Update copyright year
• •Change license type (requires project decision)
• •Update copyright holder

CONTRIBUTING.md

Guidelines for contributors.

Typical sections:

• •How to report issues
• •Development workflow
• •Code submission process
• •Testing requirements
• •Communication channels

Common updates:

• •Update workflow steps
• •Revise standards or requirements
• •Update contact information
• •Add new guidelines

Workflow for Release Preparation

When preparing a release:

1. •

   Review changes since last release

   • •Check git log or PR history
   • •Identify user-facing changes
   • •Note breaking changes or deprecations
2. •

   Update CHANGELOG.md

   • •Create new version section: [X.Y.Z] - YYYY-MM-DD
   • •Move items from Unreleased to new version
   • •Categorize: Added, Changed, Deprecated, Removed, Fixed, Security
   • •Add version comparison link
3. •

   Update README.md if needed

   • •Add new features to overview
   • •Update version numbers
   • •Revise examples if API changed
   • •Update dependencies list
4. •

   Update LICENSE if needed

   • •Update copyright year
   • •Verify copyright holder
5. •

   Review CONTRIBUTING.md

   • •Ensure workflow is current
   • •Update any changed processes

Workflow for Regular Commits

Before committing changes:

1. •

   Identify documentation impact

   • •Does change affect usage?
   • •Are there new features?
   • •Did configuration change?
   • •Are there breaking changes?
2. •

   Update CHANGELOG.md Unreleased section

   • •Add to appropriate category (Added/Changed/Fixed)
   • •Be specific and user-focused
   • •Note if breaking change
3. •

   Update README.md if needed

   • •Add new features
   • •Update examples
   • •Revise configuration steps

Best Practices

• •Keep CHANGELOG current - Update with each change, not at release time
• •Be specific - "Added user authentication" not "Made improvements"
• •User perspective - Document what users see, not internal refactoring
• •Version format - Follow Semantic Versioning (MAJOR.MINOR.PATCH)
• •Date format - Use ISO 8601 (YYYY-MM-DD)
• •Categorize correctly - Use standard categories (Added, Changed, Fixed, etc.)
• •Link commits - Reference commit SHAs or PR numbers when helpful

Output Format

Generate updated documentation files directly in /mnt/user-data/outputs/ with:

• •Proper markdown formatting
• •Consistent structure
• •Current information
• •Clear, concise descriptions