Skip to content

docs, redesign README.md — Quick Start, feature table, extract CONTRIBUTING.md #238

@steven-varga

Description

@steven-varga

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

  • CONTRIBUTING.md contains the full contribution workflow, verbatim
  • README fits on one GitHub screen before the fold for a typical desktop
  • Quick Start example compiles against v1.12.3 headers
  • Subtitle typo fixed
  • "migration in progress" language removed
  • staging and release carry the same README after the PR merges

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions