Problem
The README has two compounding issues:
staging README — wrong audience
After a good badge row, build matrix, and three-paragraph description, the document drops directly into 110 lines of contributor onboarding (issue naming, branch naming, commit format, rebase workflow, PR process). There is no Quick Start, no installation instructions, no code example, and no mention of any v1.12 features. A first-time evaluator has no reason to stay.
The migration-in-progress language ("H5CPP is being migrated…") is now stale — v1.12.3 shipped.
release README — museum exhibit
The canonical release branch still carries the original 2018 README: gcc 7.4.0, clang 6.0, download links to h5cpp.org, and a typo in the subtitle ("Paralell") that has been there since the first commit. This is what GitHub shows on the default branch landing page.
Scope
Extract
Move the entire "Migration and Contribution Workflow" section (issue naming → branch naming → commit format → rebase workflow → pull requests) to a new CONTRIBUTING.md. Keep a one-line pointer in the README.
Rewrite README structure
[badges]
[build matrix]
# H5CPP — [corrected subtitle, fix "Paralell" typo]
[description paragraph — keep current, trim bold overuse]
## Quick Start
[10-line write/read example — vector<float>, CMake find_package snippet]
## Requirements
- C++20 or later
- HDF5 ≥ 1.10.x (tested ceiling: 1.12.2)
- CMake ≥ 3.22
## Installation
- apt / brew / vcpkg one-liners
- from-source cmake steps
## Supported Types
[table: primitives, STL containers, linalg libs (Armadillo, Eigen, Blaze, Blitz++, uBLAS, IT++, dlib, std::valarray)]
## v1.12 Highlights
[brief bullets: valarray, iterator containers, float16, rank-7, complex, HDF5 1.12.2 ceiling, Windows MSVC]
## Documentation
[link to vargalabs.github.io/h5cpp]
## Contributing
[one line → CONTRIBUTING.md]
## License
Acceptance criteria
Problem
The README has two compounding issues:
staging README — wrong audience
After a good badge row, build matrix, and three-paragraph description, the document drops directly into 110 lines of contributor onboarding (issue naming, branch naming, commit format, rebase workflow, PR process). There is no Quick Start, no installation instructions, no code example, and no mention of any v1.12 features. A first-time evaluator has no reason to stay.
The migration-in-progress language ("H5CPP is being migrated…") is now stale — v1.12.3 shipped.
release README — museum exhibit
The canonical release branch still carries the original 2018 README:
gcc 7.4.0,clang 6.0, download links toh5cpp.org, and a typo in the subtitle ("Paralell") that has been there since the first commit. This is what GitHub shows on the default branch landing page.Scope
Extract
Move the entire "Migration and Contribution Workflow" section (issue naming → branch naming → commit format → rebase workflow → pull requests) to a new
CONTRIBUTING.md. Keep a one-line pointer in the README.Rewrite README structure
Acceptance criteria
CONTRIBUTING.mdcontains the full contribution workflow, verbatim