nostr_core_lib/VERSIONING.md

Version Management System

This project implements an automated version management system for C applications with auto-incrementing build numbers.

Overview

The version management system consists of:

• Semantic versioning (Major.Minor.Patch) in VERSION file
• Auto-incrementing build numbers in .build_number file
• Generated version header (version.h) with all version info
• Build-time integration via scripts/generate_version.sh

Files

Core Files

• VERSION - Contains semantic version (e.g., "1.0.0")
• .build_number - Contains current build number (auto-incremented)
• scripts/generate_version.sh - Version generation script
• version.h - Generated header (auto-created, do not edit)

Integration Files

• build.sh - Modified to call version generation
• .gitignore - Excludes generated version.h

Usage

Building

Every time you run ./build.sh, the build number automatically increments:

./build.sh  # Build #1
./build.sh  # Build #2
./build.sh  # Build #3

Version Display

The application shows version information in multiple ways:

Command Line:

./build/c_nostr --version
./build/c_nostr -v

Interactive Mode:

• ASCII art title with version
• Header shows: NOSTR TERMINAL v1.0.0 (Build #3, 2025-07-21)

Updating Semantic Version

To update the major/minor/patch version:

echo "1.1.0" > VERSION

The next build will be v1.1.0 (Build #4).

Generated Macros

The version.h file contains these macros:

#define VERSION_MAJOR 1
#define VERSION_MINOR 0
#define VERSION_PATCH 0
#define VERSION_BUILD 3
#define VERSION_STRING "1.0.0"
#define VERSION_FULL "1.0.0.3"
#define BUILD_NUMBER 3
#define BUILD_DATE "2025-07-21"
#define BUILD_TIME "14:53:32"
#define BUILD_TIMESTAMP "2025-07-21 14:53:32"
#define GIT_HASH ""
#define GIT_BRANCH ""
#define VERSION_DISPLAY "v1.0.0 (Build #3)"
#define VERSION_FULL_DISPLAY "v1.0.0 (Build #3, 2025-07-21)"

Integration in Code

Include the version header:

#include "version.h"

Use version macros:

printf("NOSTR TERMINAL %s\n", VERSION_FULL_DISPLAY);
printf("Built: %s\n", BUILD_TIMESTAMP);

Best Practices

1. Never edit version.h - it's auto-generated
2. Commit .build_number - tracks build history
3. Update VERSION manually - for semantic version changes
4. Build increments automatically - no manual intervention needed

Version History

Build numbers are persistent and increment across sessions:

• Build #1: Initial implementation
• Build #2: First rebuild test
• Build #3: Added --version flag
• Build #4: Next build...

ASCII Art Integration

The version system integrates with the ASCII art title display:

███    ██          ██████  ███████         ████████ ███████ ██████  
████   ██         ██    ██ ██                 ██    ██      ██   ██ 
██ ██  ██         ██    ██ ███████            ██    █████   ██████  
██  ██ ██         ██    ██      ██            ██    ██      ██   ██ 
██   ████ ███████  ██████  ███████ ███████    ██    ███████ ██   ██ 

NOSTR TERMINAL v1.0.0 (Build #3, 2025-07-21) - user_abc123
================================================================

This provides a professional, branded experience with clear version identification.