Version History

Transparent model evolution for reproducible energy analysis

Every VerveStacks model release will be versioned, documented, and never overwritten—ensuring your analysis will remain reproducible and citable years later.

Why Versioning Matters

Energy system models inform decisions worth billions of dollars and decades of infrastructure planning. When you reference a VerveStacks model in your analysis, you will need confidence that:

  • Your results are reproducible: The exact model version you used will remain available

  • Changes are transparent: You will understand what evolved between versions

  • Sources are traceable: Every parameter will connect to documented data sources

  • Quality is assured: Updates will undergo systematic review before release

Three-Layer Transparency

VerveStacks will maintain transparency at three levels, each serving different user needs:

Model Documentation

For energy analysts and researchers

Each model folder will include a VERSION_LOG.md that explains changes in user-friendly terms:

  • Data Updates: New datasets, improved coverage, source refreshes

  • Model Features: Enhanced capabilities, new regional coverage

  • Methodology Changes: Improved algorithms, updated assumptions

  • Known Limitations: Transparent reporting of current constraints

This documentation will travel with your model, ensuring you always know what version you’re using.

Public Development

For the energy modeling community

All model development will occur in public repositories with complete change history. This will enable:

  • Peer Review: Community validation of methodological improvements

  • Collaborative Enhancement: Contributions from global energy modeling experts

  • Academic Citation: Specific model versions can be referenced in research

  • Quality Assurance: Transparent development builds trust and accountability

Version Comparison

For institutional users

The VerveStacks website will maintain comprehensive version comparisons showing:

  • Feature Evolution: What capabilities are available across versions

  • Data Source Timeline: When and how underlying datasets were updated

  • Regional Coverage: Geographic expansion and enhancement history

  • Validation Studies: Real-world applications and accuracy assessments

Version Format

Models will follow semantic versioning: MAJOR.MINOR.PATCH

MAJOR versions (e.g., 1.0 → 2.0)

Fundamental changes to methodology or data structure that may affect comparability with previous versions.

MINOR versions (e.g., 2.1 → 2.2)

New features, data updates, or regional expansion that enhance capabilities while maintaining compatibility.

PATCH versions (e.g., 2.1.1 → 2.1.2)

Bug fixes, minor corrections, or documentation improvements that don’t change model behavior.

Update Philosophy

Quality over Speed

Updates will be released when they meaningfully improve model quality, not on arbitrary schedules.

Transparency First

Every change will be documented with clear explanation of impact and rationale.

User-Centered

Version documentation will focus on what users need to know, not technical implementation details.

Community Driven

Updates will respond to user feedback, validation findings, and collaborative improvements.

What This Means for Your Work

For Policy Analysis

Reference specific model versions in reports, knowing they remain available for verification and replication.

For Academic Research

Cite exact model versions in publications, enabling other researchers to reproduce and build on your work.

For Institutional Planning

Understand when to adopt new versions versus maintaining consistency across multi-year planning cycles.

For Collaborative Projects

Ensure all team members use the same model version, with clear documentation of any differences.

Current Release Status

VerveStacks is in active development with regular model improvements. The versioning system will ensure that as the platform matures, all releases maintain the transparency and reproducibility standards essential for credible energy system analysis.

Note

Getting Version Information: Every model folder will include complete version documentation. When sharing results, always reference the specific model version used to ensure reproducibility.