nostr_core_lib/AUTOMATIC_VERSIONING.md

NOSTR Core Library - Automatic Versioning System

Overview

The NOSTR Core Library now features an automatic version increment system that automatically increments the patch version (e.g., v0.2.0 → v0.2.1) with each build. This ensures consistent versioning and traceability across builds.

How It Works

Version Format

The library uses semantic versioning with the format: vMAJOR.MINOR.PATCH

• MAJOR: Incremented for breaking changes (manual)
• MINOR: Incremented for new features (manual)
• PATCH: Incremented automatically with each build

Automatic Increment Process

1. Version Detection: The build system scans all git tags matching v*.*.* pattern
2. Highest Version: Uses sort -V to find the numerically highest version (not chronologically latest)
3. Patch Increment: Increments the patch number by 1
4. Git Tag Creation: Creates a new git tag for the incremented version
5. File Generation: Generates nostr_core/version.h and nostr_core/version.c with build metadata

Generated Files

The system automatically generates two files during each build:

nostr_core/version.h

#define VERSION_MAJOR 0
#define VERSION_MINOR 2  
#define VERSION_PATCH 1
#define VERSION_STRING "0.2.1"
#define VERSION_TAG "v0.2.1"

#define BUILD_DATE "2025-08-09"
#define BUILD_TIME "10:42:45"
#define BUILD_TIMESTAMP "2025-08-09 10:42:45"

#define GIT_HASH "ca6b475"
#define GIT_BRANCH "master"

// API functions
const char* nostr_core_get_version(void);
const char* nostr_core_get_version_full(void);
const char* nostr_core_get_build_info(void);

nostr_core/version.c

Contains the implementation of the version API functions.

Usage

Building with Auto-Versioning

All major build targets automatically increment the version:

# Build static library (increments version)
./build.sh lib

# Build shared library (increments version)
./build.sh shared

# Build all libraries (increments version)
./build.sh all

# Build examples (increments version)
./build.sh examples

# Install to system (increments version)
./build.sh install

Non-Versioned Builds

Some targets do not increment versions:

# Clean build artifacts (no version increment)
./build.sh clean

# Run tests (no version increment)
./build.sh test

Using Version Information in Code

#include "version.h"

// Get version string
printf("Version: %s\n", nostr_core_get_version());

// Get full version with timestamp and commit
printf("Full: %s\n", nostr_core_get_version_full());

// Get detailed build information  
printf("Build: %s\n", nostr_core_get_build_info());

// Use version macros
#if VERSION_MAJOR >= 1
    // Use new API
#else
    // Use legacy API
#endif

Testing Version System

A version test example is provided:

# Build and run version test
gcc -I. -Inostr_core examples/version_test.c -o examples/version_test ./libnostr_core.a ./secp256k1/.libs/libsecp256k1.a -lm
./examples/version_test

Version History Tracking

View All Versions

# List all version tags
git tag --list

# View version history
git log --oneline --decorate --graph

Current Version

# Check current version
cat VERSION

# Or check the latest git tag
git describe --tags --abbrev=0

Manual Version Management

Major/Minor Version Bumps

For major or minor version changes, manually create the appropriate tag:

# For a minor version bump (new features)
git tag v0.3.0

# For a major version bump (breaking changes)  
git tag v1.0.0

The next build will automatically increment from the new base version.

Resetting Version

To reset or fix version numbering:

# Delete incorrect tags (if needed)
git tag -d v0.2.1
git push origin --delete v0.2.1

# Create correct base version
git tag v0.2.0

# Next build will create v0.2.1

Integration Notes

Makefile Integration

• The version.c file is automatically included in LIB_SOURCES
• Version files are compiled and linked with the library
• Clean targets remove generated version object files

Git Integration

• Version files (version.h, version.c) are excluded from git via .gitignore
• Only version tags and the VERSION file are tracked
• Build system works in any git repository with version tags

Build System Integration

• Version increment is integrated directly into build.sh
• No separate scripts or external dependencies required
• Self-contained and portable across systems

Example Output

When building, you'll see output like:

[INFO] Incrementing version...
[INFO] Current version: v0.2.0
[INFO] New version: v0.2.1
[SUCCESS] Created new version tag: v0.2.1
[SUCCESS] Generated version.h and version.c
[SUCCESS] Updated VERSION file to 0.2.1

Troubleshooting

Version Not Incrementing

• Ensure you're in a git repository
• Check that git tags exist with git tag --list
• Verify tag format matches v*.*.* pattern

Tag Already Exists

If a tag already exists, the build will continue with the existing version:

[WARNING] Tag v0.2.1 already exists - using existing version

Missing Git Information

If git is not available, version files will show "unknown" for git hash and branch.

Benefits

1. Automatic Traceability: Every build has a unique version
2. Build Metadata: Includes timestamp, git commit, and branch information
3. API Integration: Version information accessible via C API
4. Zero Maintenance: No manual version file editing required
5. Git Integration: Automatic git tag creation for version history