Skip to content

DonkRonk17/PatchNotes

BranchesTags

Repository files navigation

PatchNotes

Human-Curated Release Notes Manager & Multi-Format Publisher

Version Tests License Python Dependencies

Table of Contents

  1. The Problem
  2. The Solution
  3. Quick Start
  4. Commands Reference
  5. Entry Categories
  6. Export Formats
  7. Multi-Project Support
  8. Python API
  9. Real-World Examples
  10. Integration with Team Brain
  11. How It Works
  12. Troubleshooting
  13. Contributing
  14. License
  15. Credits

The Problem

Shipping software is exciting. Writing release notes is... not.

Every release you face the same pain:

  • Inconsistency: Every version looks different — different tone, different structure
  • Multi-platform torture: Discord wants emoji-heavy markdown, your blog wants HTML, customers want email — same content, 3 manual rewrites
  • Git history != User news: Auto-generated changelogs from commits are for developers, not users
  • Version amnesia: "What did we change in v1.3.2?" requires digging through git logs
  • Blank page paralysis: Starting release notes from scratch every time wastes 20-30 minutes

Result: Release communication is neglected, inconsistent, or skipped entirely.

The Solution

PatchNotes gives you a simple, structured system:

  1. Create a draft for your next version
  2. Add entries as you build (never forget a feature again)
  3. Publish when ready
  4. Export to any format with one command
# 30-second complete release notes workflow
patchnotes new v1.5.0 "Spring Update"
patchnotes add new "Added dark mode"
patchnotes add fixed "Fixed crash on Windows 11"
patchnotes add performance "Startup is 40% faster"
patchnotes publish
patchnotes export v1.5.0 --format discord

That's it. One place, all formats, consistent forever.

PatchNotes vs ChangeLog

Both are Team Brain tools. They solve different problems:

Feature PatchNotes ChangeLog
Source Human-written Auto-generated from git
Audience End users Developers
Tone Friendly, narrative Technical
Format output 6 formats (Discord, HTML, email...) Markdown changelog
Git required? No Yes
Best for Product releases Developer changelog

Use both — they complement each other perfectly.

Quick Start

Installation

# Option 1: Clone and use directly
git clone https://github.com/DonkRonk17/PatchNotes.git
cd PatchNotes
python patchnotes.py --help

# Option 2: Add to PATH (Windows)
# Add PatchNotes directory to your PATH environment variable
# Then run: patchnotes --help

# Option 3: pip install (local)
pip install -e .
patchnotes --help

Requirements: Python 3.7+ | Zero external dependencies

Your First Release Notes

# Step 1: Create a draft for your next version
patchnotes new v1.0.0 "First Public Release"
# [OK] Draft created: v1.0.0 - First Public Release

# Step 2: Add entries as you build
patchnotes add new "Complete project scaffolding system"
patchnotes add new "Supports Python, Node.js, and Rust templates"
patchnotes add new "Zero external dependencies"

# Step 3: Check your draft
patchnotes list
# Draft: v1.0.0 - First Public Release
#   [NEW] New
#     - Complete project scaffolding system
#     - Supports Python, Node.js, and Rust templates
#     - Zero external dependencies

# Step 4: Publish when ready
patchnotes publish
# [OK] Published: v1.0.0 - First Public Release (3 entries)

# Step 5: Export for your announcement
patchnotes export v1.0.0 --format discord

That's it! Your release notes are now managed, structured, and ready for any platform.

Commands Reference

new - Create Draft Release

patchnotes new <version> [title]
patchnotes new v2.0.0
patchnotes new v2.0.0 "Major Overhaul"
patchnotes new v2.0.0-beta "Beta Preview"
patchnotes new v2.0.0 --project myapp

Creates a new draft release. Only one draft per project at a time.

Supported version formats:

  • v1.2.3 — standard semantic version
  • 1.2.3 — without v prefix (normalized to v1.2.3)
  • v2.0.0-beta — pre-release identifiers
  • v1.0.0-alpha.1 — dotted pre-release
  • v1.2 — major.minor only

add - Add Entry to Draft

patchnotes add <category> <text>
patchnotes add new "Added user authentication"
patchnotes add fixed "Fixed database timeout on large queries"
patchnotes add changed "Login flow now uses email instead of username"
patchnotes add security "Patched SQL injection vulnerability"
patchnotes add performance "Dashboard loads 60% faster"
patchnotes add coming "Mobile app coming in v2.0"

Category accepts aliases (new/add/added, fix/fixed/bug, change/changed, etc.)

list - View Draft or Release

patchnotes list              # Show current draft
patchnotes list v1.5.0       # Show specific published version
patchnotes list --project myapp

Displays entries grouped by category with entry IDs.

delete - Remove Entry from Draft

patchnotes delete abc123     # Delete by entry ID (6 chars shown in list)
patchnotes delete abc1       # Prefix match also works

IDs are shown when you run patchnotes list.

publish - Publish Draft

patchnotes publish
patchnotes publish --project myapp

Finalizes the draft as a published release. The draft is cleared. Once published, a release is immutable.

discard - Discard Draft

patchnotes discard --yes
patchnotes discard --project myapp --yes

Permanently deletes the current draft. Requires --yes to prevent accidents.

export - Export Release Notes

patchnotes export                           # Export current draft (markdown)
patchnotes export v1.5.0                    # Export published version
patchnotes export v1.5.0 --format discord   # Discord format
patchnotes export v1.5.0 --format html      # HTML format
patchnotes export v1.5.0 --format email     # Email format
patchnotes export v1.5.0 --format text      # Plain text
patchnotes export v1.5.0 --format json      # Raw JSON
patchnotes export v1.5.0 -f discord -o discord_post.txt  # Save to file

Available formats: markdown (default), html, discord, email, text, json

history - View Release History

patchnotes history
patchnotes history --limit 5    # Show last 5 releases
patchnotes history -n 3 --project myapp

Lists published releases, newest first.

status - Project Status

patchnotes status
patchnotes status --project myapp

Shows draft state, published count, and latest version.

projects - List All Projects

patchnotes projects

Lists all projects with release notes.

categories - List Categories

patchnotes categories

Shows all valid entry categories and their accepted aliases.

formats - List Export Formats

patchnotes formats

Shows all valid export formats and their descriptions.

Entry Categories

PatchNotes uses 8 categories that cover any type of release change:

Category Icon Aliases Use for
New [NEW] new, add, added New features, additions
Fixed [FIX] fix, fixed, bug, bugfix Bug fixes, crash fixes
Changed [CHG] change, changed, update Behavior changes, updates
Removed [REM] remove, removed, delete Removed features
Security [SEC] security, sec Security patches, CVEs
Performance [PRF] perf, performance, speed Speed, memory improvements
Known Issues [KNW] known, issues, issue Documented problems not yet fixed
Coming Soon [COM] coming, next, planned Sneak peeks at next version

Category order is preserved in all exports. New features always appear before fixes, fixes before changes, etc.

Export Formats

Markdown (default)

Standard GitHub-flavored markdown. Perfect for GitHub Releases, pull requests, documentation.

## v1.5.0 - Spring Update
*March 12, 2026*

### New
- Added dark mode

### Fixed
- Fixed crash on Windows 11

HTML

Self-contained HTML article element. Drop into any webpage, email HTML template, or documentation system.

<article class="patch-notes">
  <h2>v1.5.0 - Spring Update</h2>
  <p class="date">March 12, 2026</p>
  <section class="category">
    <h3>New</h3>
    <ul>
      <li>Added dark mode</li>
    </ul>
  </section>
</article>

Note: All user content is HTML-escaped for XSS safety.

Discord

Discord-formatted with emoji category headers. Copy-paste directly into your announcements channel.

**v1.5.0 - Spring Update**
March 12, 2026

:sparkles: **New**
- Added dark mode

:wrench: **Fixed**
- Fixed crash on Windows 11

Discord emoji per category:

  • New: :sparkles: | Fixed: :wrench: | Changed: :arrows_counterclockwise:
  • Removed: :wastebasket: | Security: :shield: | Performance: :zap:
  • Known Issues: :warning: | Coming Soon: :crystal_ball:

Email

Plain-text email body with Subject line. Copy into any email client.

Subject: Release Notes: v1.5.0 - Spring Update

What's new in v1.5.0 (March 12, 2026):

NEW:
  * Added dark mode

FIXED:
  * Fixed crash on Windows 11

Text

ASCII-art formatted plain text. Works in any terminal, notepad, or cat output.

v1.5.0 - Spring Update
Released: March 12, 2026
=============================

[NEW] New
  - Added dark mode

[FIX] Fixed
  - Fixed crash on Windows 11

JSON

Raw JSON of the release record. Use for custom integrations, APIs, or further processing.

{
  "version": "v1.5.0",
  "title": "Spring Update",
  "status": "published",
  "entries": [...]
}

Multi-Project Support

Manage release notes for multiple projects on the same machine:

# Project: beacon-hq
patchnotes new v3.0.0 "BCH Update" --project beacon-hq
patchnotes add new "Real-time sync improvements" --project beacon-hq

# Project: atlas-tools
patchnotes new v1.0.0 "Initial Release" --project atlas-tools
patchnotes add new "Zero dependencies" --project atlas-tools

# View all projects
patchnotes projects
#   Projects (2):
#     - atlas-tools
#     - beacon-hq

# Each project is fully isolated
patchnotes status --project beacon-hq
patchnotes history --project atlas-tools

Storage: Each project gets its own ~/.patchnotes/<project>.json file.

Python API

Use PatchNotes directly in Python scripts:

from patchnotes import PatchNotes

pn = PatchNotes(project="myapp")

# Create a release
pn.new_release("v2.0.0", "Major Update")

# Add entries
pn.add_entry("new", "Complete redesign of the dashboard")
pn.add_entry("fixed", "Fixed memory leak in data pipeline")
pn.add_entry("security", "Patched authentication bypass")

# Check status
s = pn.status()
print(f"Draft: {s['draft']['version']} with {s['draft']['entries']} entries")

# Publish
released = pn.publish()
print(f"Published: {released['version']}")

# Export all formats
for fmt in ["markdown", "html", "discord", "email", "text", "json"]:
    output = pn.export("v2.0.0", fmt=fmt)
    with open(f"release-{fmt}.txt", "w") as f:
        f.write(output)

# View history
for r in pn.history(limit=5):
    print(f"  {r['version']} - {r.get('title', '')} ({len(r['entries'])} entries)")

API Reference

class PatchNotes:
    def __init__(self, project: str = "default", data_dir: Path = None)
    
    # Release management
    def new_release(self, version: str, title: str = "") -> dict
    def add_entry(self, category: str, text: str) -> dict
    def delete_entry(self, entry_id: str) -> bool
    def publish(self) -> dict
    def discard_draft(self) -> bool
    
    # Queries
    def get_draft(self) -> dict | None
    def get_release(self, version: str) -> dict | None
    def list_entries(self, version: str = None) -> list
    def history(self, limit: int = 10) -> list
    def status(self) -> dict
    def export(self, version: str = None, fmt: str = "markdown") -> str
    def list_projects(self) -> list

# Utility functions
def validate_version(version: str) -> bool
def validate_category(category: str) -> bool

Real-World Examples

Game Development Studio (Discord Announcement)

patchnotes new v0.8.3 "Patch 8.3 - Balance Update" --project mygame
patchnotes add fixed "Fixed soft-lock in dungeon boss fight"
patchnotes add fixed "Corrected damage calculation for fire spells"
patchnotes add changed "Reduced mana cost for healing spells by 15%"
patchnotes add performance "Improved loading times in city area"
patchnotes add coming "New dungeon biome coming in v0.9"
patchnotes publish
patchnotes export v0.8.3 --format discord

SaaS Product (GitHub Release)

patchnotes new v3.1.0 "March Release" --project saas-platform
patchnotes add new "Multi-tenant SSO support"
patchnotes add new "Bulk CSV export for reports"
patchnotes add fixed "Fixed timezone bug in scheduler"
patchnotes add security "Updated OAuth library to patch CVE-2026-1234"
patchnotes add performance "API response time reduced by 40%"
patchnotes publish
patchnotes export v3.1.0 --format markdown -o RELEASE_NOTES.md

Open Source Library (PyPI release)

patchnotes new v2.0.0 "2.0 - Breaking Changes" --project mylib
patchnotes add changed "Renamed MyClass to BetterClass (breaking)"
patchnotes add removed "Removed deprecated process_old() method"
patchnotes add new "Added async support"
patchnotes add new "Python 3.12 compatibility"
patchnotes add security "Removed eval() usage from config parser"
patchnotes publish
patchnotes export v2.0.0

Daily Standup Notes (Text format)

patchnotes add new "Completed user profile page" --project sprint-42
patchnotes add fixed "Fixed the weird pagination bug"
patchnotes add changed "Moved deploy to Friday EOD"
patchnotes export --format text  # Quick text summary for standup

AI Agent Build Log (Session Notes)

# ATLAS logs tool builds as patch notes
patchnotes new v1.0.0 "PatchNotes - Initial Build" --project atlas-session
patchnotes add new "Core release management (new/add/publish/export)"
patchnotes add new "6 export formats: markdown/html/discord/email/text/json"
patchnotes add new "8 entry categories with alias support"
patchnotes add new "Multi-project support"
patchnotes add new "45 tests at 100% pass rate"
patchnotes publish --project atlas-session
patchnotes export v1.0.0 --format text --project atlas-session

Integration with Team Brain

SynapseLink Integration

import subprocess
from patchnotes import PatchNotes

# Get release notes after build
pn = PatchNotes(project="beacon-hq")
notes = pn.export("v3.0.0", fmt="text")

# Post to Synapse
subprocess.run([
    "python", "D:/BEACON_HQ/PROJECTS/AutoProjects/SynapseLink/synapselink.py",
    "--to", "FORGE,CLIO", "--subject", "BCH v3.0.0 Released",
    "--body", notes
])

BCH Automation

After a successful build, BCH can auto-export Discord release notes:

from patchnotes import PatchNotes

pn = PatchNotes(project="bch")
discord_notes = pn.export(fmt="discord")

# Post to Discord webhook
# (integrate with BCH's existing webhook system)

ConfigManager Integration

from configmanager import ConfigManager
from patchnotes import PatchNotes

config = ConfigManager()
default_project = config.get("patchnotes.default_project", "default")
default_format = config.get("patchnotes.default_format", "markdown")

pn = PatchNotes(project=default_project)
output = pn.export(fmt=default_format)

MemoryBridge Integration

from memorybridge import MemoryBridge
from patchnotes import PatchNotes

pn = PatchNotes(project="myapp")
history = pn.history(limit=20)

bridge = MemoryBridge()
bridge.set("myapp_release_history", history)
bridge.sync()

How It Works

Data Flow

User Input (CLI)
      |
      v
Argument Parser (argparse)
      |
      v
Command Function (cmd_new, cmd_add, etc.)
      |
      v
PatchNotes Core Class
      |
      +-> StorageManager (load/save ~/../patchnotes/project.json)
      |
      +-> ExportEngine (markdown/html/discord/email/text/json)
      |
      v
Output (stdout or file)

Storage Format

All data is stored in ~/.patchnotes/ as JSON files:

  • default.json — default project
  • myapp.json — "myapp" project
  • myapp.backup.json — last-known-good backup

The atomic write pattern prevents corruption:

  1. Write to project.tmp
  2. Copy current project.json to project.backup.json
  3. Replace project.json with project.tmp

Version Normalization

All versions are normalized to v-prefix form:

  • 1.2.3 → v1.2.3
  • v1.2.3 → v1.2.3
  • 2.0.0-beta → v2.0.0-beta

Category System

Categories are processed in canonical order (New → Fixed → Changed → Removed → Security → Performance → Known Issues → Coming Soon) in all export formats. This ensures consistent presentation regardless of entry order.

Troubleshooting

"A draft already exists"

You can only have one draft at a time. Options:

patchnotes status        # Check what version is in draft
patchnotes publish       # If it's ready, publish it
patchnotes discard --yes # If you want to abandon it

"Version already published"

patchnotes history       # Check if it was accidentally published
# If you need to fix it, manually edit ~/.patchnotes/project.json
# (Version is immutable once published by design)

"Invalid version format"

PatchNotes uses semantic versioning:

# Valid
patchnotes new v1.2.3
patchnotes new 2.0.0
patchnotes new v1.0.0-beta

# Invalid
patchnotes new "version 1"
patchnotes new v1
patchnotes new "1.2.3.4.5"

"No entries" after publish

Check that you added entries before publishing:

patchnotes list    # Should show entries
patchnotes add new "At least one entry is good practice"
patchnotes publish

Storage Location

All data is stored in ~/.patchnotes/:

  • Windows: C:\Users\<username>\.patchnotes\
  • Linux/macOS: /home/<username>/.patchnotes/ or ~/.patchnotes/

To use a custom directory, use the Python API:

from patchnotes import PatchNotes
from pathlib import Path

pn = PatchNotes(project="myapp", data_dir=Path("/custom/path"))

Unicode on Windows

PatchNotes handles Windows encoding automatically. If you see encoding errors, ensure you're using Python 3.7+.

Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-format)
  3. Write tests for new functionality
  4. Ensure all tests pass: python test_patchnotes.py
  5. Submit a pull request

Code standards:

  • Zero external dependencies (stdlib only)
  • Type hints for all public functions
  • Docstrings for all public functions/classes
  • No Unicode emojis in Python code (ASCII only: [OK], [X], [!])
  • 100% test pass rate required

License

MIT License — see LICENSE for details.

Credits

Built by: ATLAS (Team Brain) For: Logan Smith / Metaphy LLC Tool #: 101 in the AutoProjects collection Why Built: Every project needs release notes. Every release needs multiple formats. One tool to rule them all. Part of: Beacon HQ / Team Brain Ecosystem Date: March 12, 2026

Team Brain Ecosystem:

  • FORGE - Orchestrator / Reviewer
  • ATLAS - Implementation Lead (this tool)
  • CLIO - CLI Agent, Trophy Keeper
  • NEXUS - VS Code Architect
  • BOLT - Free Executor

Philosophy: "Build something extremely useful, that is easy to use, solves a common problem, and has clear instructions on how to implement, install and use."

One World. One Family. One Love.

PatchNotes v1.0.0 — Quality Score: 100/100 — 45 tests passing

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages