How It Works

Nyron reads your Git history and parses conventional commits to generate structured changelogs automatically.

The Process

Nyron follows a systematic 7-step approach to generate your changelogs and create releases:

Step 1: Tag Discovery

Nyron determines which nyron-release@* tags to use based on the mode:

Mode 1: New Tag Release (with -n flag)

• Finds the latest tag (the one you just pushed with push-tag)
• Finds the previous tag to compare against
• Used when a nyron-release tag was just created and pushed

Mode 2: Standard Release (without -n flag)

• Finds the latest nyron-release@* tag
• Uses that tag as the starting point
• Used for creating a release from existing state

Step 2: Commit Extraction

Nyron retrieves commits based on the tags discovered:

• With -n flag: Fetches commits BETWEEN the previous tag and the latest tag using GitHub API
• Without -n flag: Fetches commits from the latest tag to HEAD
• If no commits are found, the release is skipped (nothing new to release)

Step 3: Commit Parsing

Each commit message is analyzed using conventional commit format:

• Parses commit syntax: Extracts type (feat, fix, docs, etc.), scope, and message
• Groups by type: Organizes commits into categories (features, fixes, breaking changes, etc.)
• Extracts scopes: Identifies package scopes from commit messages (e.g., feat(cli): add feature)
• Filters meta commits: Version bumps, changelog updates, and other meta commits are automatically excluded

Step 4: Version Detection

Nyron reads version information from .nyron/meta.json:

• Contains package names, old versions, and new versions
• Generated during bump or push-tag operations
• Used to show which packages were updated and by how much in the changelog

Step 5: Changelog Generation

Generates markdown changelog from parsed commits and version data:

• Formats into sections: Breaking Changes, Features, Bug Fixes, Chores, etc.
• Includes package version updates and commit details
• Enriches with GitHub data (author usernames, avatars, commit URLs) if GitHub token is configured
• Produces clean, readable markdown suitable for GitHub releases

Step 6: GitHub Release Creation

Creates the GitHub release:

• Dry Run: Generates changelog and prints to console (no GitHub release created)
• Wet Run: Creates actual GitHub release with the generated changelog as body
• Uses the determined release tag (pushed tag with -n, latest tag without -n)
• Publishes to the repository's releases page

Step 7: Tag Creation (Next Release Boundary)

Only executed without -n flag and not in dry-run mode:

• Creates a new nyron-release@* tag AFTER the release is published
• Updates meta.json with the new tag
• This tag marks the boundary for the NEXT release, not the current one

Example Output

Here's what a generated changelog section looks like:

## Features
- **auth**: add OAuth2 login ([@username](https://github.com/username)) [[a1b2c3d](https://github.com/owner/repo/commit/a1b2c3d)]

## Bug Fixes
- **api**: resolve memory leak in endpoint ([@username](https://github.com/username)) [[e4f5g6h](https://github.com/owner/repo/commit/e4f5g6h)]

## Version Updates
- **cli**: 1.0.0 → 1.1.0
- **sdk**: 2.3.0 → 2.4.0

The changelog includes version information from .nyron/meta.json, showing which packages were updated and their version changes.

Understanding Release Boundaries

Nyron uses a dual-tag system that separates version tracking from release boundaries:

Project Tags (Version Tracking)

• Created by nyron bump command
• Format: Based on your tagPrefix config (e.g., v1.2.0, @pkg/name@1.2.0)
• Purpose: Track package versions in your repository
• Not used as release boundaries

Nyron-Release Tags (Release Boundaries)

• Created by nyron push-tag command or nyron release command (without -n flag)
• Format: nyron-release@2024-01-15@14-30-25.123
• Purpose: Mark release boundaries for GitHub releases
• Only these tags determine which commits are included in releases

Mental Model

Here's how Nyron-release tags work as release boundaries:

nyron-release@date1 ---- A ---- B ---- C ---- nyron-release@date2 ---- D ---- E ---- HEAD
                         └──────┬──────┘                                └─────┬─────┘
                    commits for date2 release                    commits since date2

Tag Creation Timing:

• nyron push-tag: Creates and pushes the tag immediately at the current HEAD
• nyron release (without -n): Creates a new tag AFTER the release is published. This tag marks the boundary for the NEXT release, not the current one.
• nyron release (with -n): Does NOT create a tag. Uses the existing tag you pushed with push-tag and fetches commits BETWEEN the previous tag and the tag you just pushed.

Two Release Modes

Mode 1: New Tag Release (with -n flag)

Used when a nyron-release tag was just created and pushed:

1. Finds the latest tag (the one just pushed)
2. Finds the previous tag to compare against
3. Gets commits BETWEEN these two tags
4. Creates GitHub release for the pushed tag
5. Does NOT create a new tag

Use case: You've already pushed a tag with push-tag and want to create a release for commits between the previous release and the tag you just pushed.

Mode 2: Standard Release (without -n flag)

Used for creating a release from existing state:

1. Finds the latest nyron-release@* tag
2. Gets commits from that tag to HEAD
3. Creates GitHub release for the latest tag
4. Creates a new nyron-release tag AFTER the release (marks boundary for NEXT release)

Use case: You want to create a release for all commits since the last release, and have Nyron automatically mark where the next release will start from.

What Makes It Work

Conventional Commits

Nyron relies on the conventional commits specification. This standardized format allows Nyron to:

• Automatically categorize changes
• Generate meaningful changelogs
• Determine the scope of changes

Learn more about conventional commits format.

GitHub Integration

The GitHub integration provides rich context:

• Author attribution: See who made each change
• Commit links: Jump directly to the commit on GitHub
• Repository metadata: Accurate project information

While GitHub is currently required, support for other platforms is planned.

Benefits

By automating the changelog generation process, Nyron:

• ✅ Saves time on manual changelog writing
• ✅ Ensures consistency across releases
• ✅ Reduces human error in version management
• ✅ Keeps your team focused on building features

Next Steps

• Learn about conventional commit syntax
• See a typical versioning workflow
• Explore commands to start using Nyron