What is VerBeat?
VerBeat is a 3D versioning system that combines manual semantic milestones with automated time-based and activity-driven versioning. It bridges the gap between traditional semantic versioning and calendar-based approaches, providing a practical solution for modern development workflows.
Why VerBeat?
Existing versioning systems have fundamental limitations that waste time and provide inadequate information:
📅 Calendar Versioning (CalVer)
Pros: Automatic, no version decisions needed, clear time context
Problem: All versions are equal - a version only tells you "when" it was released, not "what" changed or "how significant" it is. You lose semantic meaning entirely.
🎯 Semantic Versioning (SemVer)
Pros: Clear indication of change significance and compatibility
Problem: Requires constant decision-making about what constitutes "breaking" vs "minor" changes. Teams waste time debating version bumps for 90% of releases where the distinction is meaningless. The complexity often leads to version inflation or inconsistent practices.
VerBeat solves both problems: You get automatic time-based versioning (like CalVer) while preserving meaningful semantic milestones (like SemVer) - but only when you actually need them. No more version debates for routine releases.
Version Format
M.YYMM.C
Where:
- M - Manual version bump (semantic milestone)
- YYMM - Year and month (calendar context)
- C - Commit count for the current month (activity tempo)
SemVer Compliant
VerBeat follows Semantic Versioning 2.0.0:
- Major (M): Manual semantic milestones
- Minor (YYMM): Calendar-based versioning
- Patch (C): Activity-based versioning
Versions are stored as Git tags: v{M}.{YYMM}.{C}
Problems VerBeat Solves
🔄 Manual Versioning Pain
Eliminates tedious manual version bumps while retaining human judgment for meaningful changes.
⏰ Time Context
Provides clear temporal context that semantic versioning lacks, making releases more relatable.
📊 Activity Insight
Commit count reveals development velocity and iteration intensity at a glance.
🤖 CI/CD Friendly
Automated parts reduce merge conflicts and integrate seamlessly with modern pipelines.
👥 Human Readable
Clear, intuitive format that's easy to understand and communicate across teams.
🎯 Semantic Meaning
Preserves intentional versioning while adding automated time and activity context.
Example Usage
Consider a project with the following verbeat.version file:
1 # Initial release
2 # Breaking API changes
On July 15, 2025, with 14 commits this month, the version would be:
2.2507.14
This tells us: Manual version 2, July 2025, 14 commits this month.
When to Use VerBeat
VerBeat is ideal for:
- Internal tools and platforms
- SaaS services with regular releases
- Fast-paced development projects
- API-based services
- Projects where release clarity is more valuable than strict compatibility guarantees
Implementations
VerBeat implementations are available for:
- Python - Complete library with CLI tools
- Node.js - Complete library with CLI tools
- More coming soon...
Interactive VerBeat Demo
Experiment with the VerBeat versioning system in real-time.
2.2507.14
How it works
Change the manual version, date, or add commits to see how the VerBeat version updates automatically. The commit counter resets when you change to a new month.
VerBeat Playbook
Follow this step-by-step workflow to get started with VerBeat. This example uses Node.js with npx, but Python users can replace npx verbeat with uvx verbeat.
1. Project Setup
Start with a new Node.js project and install VerBeat:
$ mkdir my-awesome-project
$ cd my-awesome-project
$ git init
$ npx verbeat init "Project kickoff"
Created verbeat.version
VerBeat initialized with version: 1.2507.0
2. Check Current Version
Monitor your project's current version during development:
$ npx verbeat version
1.2507.2
3. Major Version Bump (When Needed)
Only bump the major version for significant releases. In all other cases, version updates automatically:
$ npx verbeat bump "Breaking API changes"
Bumped to version 2
$ cat verbeat.version
1 # Project kickoff
2 # Breaking API changes
$ npx verbeat version
2.2507.2
4. Push to CI/CD
Push your changes to trigger automated version management:
$ git add verbeat.version
$ git commit -m "chore: bump version to 2"
$ git push origin main
5. CI/CD Automation
Set up GitHub Actions to handle version management automatically:
name: Release
on:
push:
branches: [main]
permissions:
contents: write
jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '18'
- name: Create Git Tag
run: |
VERSION=$(npx verbeat version)
git tag -a "v$VERSION" -m "VerBeat $VERSION: ${{ github.event.head_commit.message }}"
git push origin "v$VERSION"
6. Workflow Summary
That's it! Your complete VerBeat workflow:
Setup
Initialize: npx verbeat init "Project kickoff"
Creates verbeat.version file
Develop
Monitor: npx verbeat version
Version updates automatically with commits
Release
Bump: npx verbeat bump "Breaking changes"
Only when major version change is needed
Deploy
Push: git push origin main
CI automatically creates tags and updates website
CI/CD Integration Examples
VerBeat integrates seamlessly with popular CI/CD systems. Here are examples for the most common platforms:
GitHub Actions
Most popular for open source projects with native GitHub integration:
name: Release
on:
push:
branches: [main]
permissions:
contents: write
jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '18'
- name: Create Git Tag
run: |
VERSION=$(npx verbeat version)
git tag -a "v$VERSION" -m "VerBeat $VERSION: ${{ github.event.head_commit.message }}"
git push origin "v$VERSION"
Travis CI
Classic choice for open source projects with simple configuration:
language: node_js
node_js: 18
script:
- npm test
deploy:
provider: script
script: |
VERSION=$(npx verbeat version)
git tag -a "v$VERSION" -m "VerBeat $VERSION: Travis CI release"
git push origin "v$VERSION"
on:
branch: main
condition: $TRAVIS_PULL_REQUEST = false
CircleCI
Popular for complex workflows with excellent Docker support:
version: 2.1
jobs:
test:
docker:
- image: cimg/node:18
steps:
- checkout
- run: npm install
- run: npm test
release:
docker:
- image: cimg/node:18
steps:
- checkout
- run: |
VERSION=$(npx verbeat version)
git tag -a "v$VERSION" -m "VerBeat $VERSION: CircleCI release"
git push origin "v$VERSION"
workflows:
version: 2
test-and-release:
jobs:
- test
- release:
requires:
- test
filters:
branches:
only: main
GitLab CI/CD
Integrated CI/CD for GitLab repositories with powerful pipelines:
stages:
- test
- release
test:
stage: test
image: node:18
script:
- npm install
- npm test
release:
stage: release
image: node:18
script:
- VERSION=$(npx verbeat version)
- git tag -a "v$VERSION" -m "VerBeat $VERSION: GitLab CI release"
- git push origin "v$VERSION"
only:
- main
when: manual
Key Integration Points
All examples follow these principles:
- Use
npx verbeat version - Gets current version for tag creation
- Create tags only on main branch - Prevents duplicate tags from feature branches
- Run tests before release - Ensures quality before versioning
- Use descriptive tag messages - Includes VerBeat version and CI system
