# HDF5 Version Management System Implementation Summary

## Overview

Implemented a centralized version management system for HDF5 that:
- Uses a single source of truth (`VERSION.txt`)
- Generates version information in all necessary files via templates
- Prevents accidental regeneration during normal builds
- Provides helper scripts for easy version updates

## What Was Implemented

### 1. Core Files Created

#### `VERSION.txt` (Single Source of Truth)
- Simple `KEY=VALUE` format
- Contains: `MAJOR`, `MINOR`, `RELEASE`, `SUBRELEASE`
- Current version: **2.1.0** (MAJOR=2, MINOR=1, RELEASE=0, SUBRELEASE=empty)

#### `config/cmake/HDF5Version.cmake` (Version Parser)
- CMake function `HDF5_READ_VERSION()`
- Reads `VERSION.txt` and sets CMake variables
- Validates required fields
- Generates derived strings (`HDF5_VERS_STR`, `HDF5_VERS_INFO`)

### 2. Template Files Created (`.in` files)

These contain `@VARIABLE@` placeholders that get replaced during regeneration:

1. **`src/H5public.h.in`** - C header with version macros
2. **`README.md.in`** - Documentation with version string
3. **`release_docs/CHANGELOG.md.in`** - Changelog with version info
4. **`config/cmake/scripts/HDF5config.cmake.in`** - CMake configuration
5. **`config/examples/HDF5AsSubdirMacros.cmake.in`** - CMake macros
6. **`java/hdf/hdf5lib/H5.java.in`** - Java bindings version
7. **`java/test/TestH5.java.in`** - Java test version
8. **`java/src-jni/hdf/hdf5lib/H5.java.in`** - JNI bindings version
9. **`java/src-jni/test/TestH5.java.in`** - JNI test version

### 3. Helper Scripts

#### `bin/update-version.sh` (Linux/Mac/Git Bash)
- Reads `VERSION.txt`
- Creates temporary CMake build directory
- Regenerates all version files
- Shows `git diff` summary
- Provides commit instructions
- Auto-cleanup of temp directory

#### `bin/update-version.bat` (Windows)
- Same functionality as `.sh` script
- Native Windows batch file
- Works in Command Prompt or PowerShell

### 4. CMake Integration Changes

Modified `CMakeLists.txt` to:
- Include `HDF5Version.cmake` and call `HDF5_READ_VERSION()`
- Set CMake project version variables from VERSION.txt
- Add `HDF5_REGENERATE_VERSION_FILES` option (OFF by default)
- Guard `configure_file()` calls with the option
- Show status messages indicating whether regeneration is happening
- Generate Java files regardless of `HDF5_BUILD_JAVA` setting (when regenerating)

**Key behavior:**
- **Normal builds**: Use existing generated files (no regeneration)
- **Version updates**: Explicitly set `-DHDF5_REGENERATE_VERSION_FILES=ON`


## Files Modified vs Created

### Modified (Already Existed)
- `CMakeLists.txt` - Changed version reading logic and added guard
- `src/H5public.h` - Generated from new template (was previously static)
- `README.md` - Generated from new template
- `release_docs/CHANGELOG.md` - Generated from new template
- `config/cmake/scripts/HDF5config.cmake` - Generated from new template
- `config/examples/HDF5AsSubdirMacros.cmake` - Generated from new template

### Created (New Files)
- `VERSION.txt` ✨ **Single source of truth**
- `config/cmake/HDF5Version.cmake` ✨ **Version parser**
- `bin/update-version.sh` ✨ **Helper script (Linux/Mac)**
- `bin/update-version.bat` ✨ **Helper script (Windows)**
- `CLAUDE.md` ✨ **Documentation** (was created/updated)
- All `.in` template files (9 files total)

## Version Update Workflow

### For Developers/Maintainers

When you need to update the version:

```bash
# 1. Edit VERSION.txt
vim VERSION.txt
Note:  there could be another script to take a version argument and write it
       to VERSION.txt to avoid editing it directly. 

# 2. Run the helper script
./bin/update-version.sh        # Linux/Mac
# or
bin\update-version.bat         # Windows

# 3. Review changes
git diff

# 4. Commit all changes together
git add VERSION.txt src/H5public.h README.md release_docs/CHANGELOG.md \
        config/cmake/scripts/HDF5config.cmake \
        config/examples/HDF5AsSubdirMacros.cmake \
        java/hdf/hdf5lib/H5.java java/test/TestH5.java \
        java/src-jni/hdf/hdf5lib/H5.java java/src-jni/test/TestH5.java
git commit -m "Update version to X.Y.Z"
```

### For End Users (Building from Source)

Nothing changes! Users continue to build normally:
```bash
cmake --workflow --preset ci-StdShar-GNUC
```

The version files are already generated and checked into the repository.

## Benefits

1. **Single Source of Truth** - Only edit one file (`VERSION.txt`)
2. **Consistency** - All files guaranteed to have matching version info
3. **No Manual Edits** - Reduces human error in version updates
4. **Safe Builds** - Normal builds don't modify source tree
5. **Easy Updates** - Simple script-based workflow
6. **Well Documented** - Clear instructions in CLAUDE.md
7. **Platform Support** - Both Unix and Windows scripts provided
8. **Git-Friendly** - Shows exactly what changed for review

## Technical Details

### CMake Variables Set

From `VERSION.txt`, these variables are set:
- `HDF5_VERS_MAJOR`, `HDF5_VERS_MINOR`, `HDF5_VERS_RELEASE`, `HDF5_VERS_SUBRELEASE`
- `HDF5_VERS_STR` (e.g., "2.1.0" or "2.1.0-rc1")
- `HDF5_VERS_INFO` (e.g., "HDF5 library version: 2.1.0")
- `HDF5_VERSION_PLAIN` (always "X.Y.Z" without subrelease)
- Plus backwards-compatible `H5_VERS_*` variants

### Template Substitution

In `.in` files:
- `@HDF5_VERS_MAJOR@` → `2`
- `@HDF5_VERS_MINOR@` → `1`
- `@HDF5_VERS_RELEASE@` → `0`
- `@HDF5_VERS_SUBRELEASE@` → ``
- `@HDF5_VERS_STR@` → `2.1.0`
- `@HDF5_VERSION_PLAIN@` → `2.1.0`

### Optional Improvements

- Add the scripts to `.gitattributes` as executable
- Consider adding a CMake target like `update-version` for convenience
- Add CI check to ensure VERSION.txt matches generated files
- Create a GitHub Actions workflow to automate version bumps