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`
```c
#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:

```bash
# 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:

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

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

### Using Version Information in Code

```c
#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:

```bash
# 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
```bash
# List all version tags
git tag --list

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

### Current Version
```bash
# 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:

```bash
# 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:

```bash
# 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