docs: add canonical name column to registered filter plugins (H5Z_class3_t)#256
Open
brtnfld wants to merge 2 commits into
Open
docs: add canonical name column to registered filter plugins (H5Z_class3_t)#256brtnfld wants to merge 2 commits into
brtnfld wants to merge 2 commits into
Conversation
Introduces the canonical filter name as a normative field in the registry, in preparation for HDF5 v3 (H5Z_class3_t) plugins where the H5Z_class_t::name field becomes a load-bearing string identifier rather than a free-form debug comment. - Adds a Canonical Name column to the registry table, pre-filled with proposed names marked (proposed) pending maintainer confirmation. - Adds a "Canonical Names (HDF5 v3 / H5Z_class3_t)" section documenting where the name appears, the syntactic rules ([A-Za-z0-9_.-], <=255 bytes, case-sensitive), the first-registered-wins allocation policy, and the self-namespacing convention for unregistered plugins. - Extends "How to Register HDF5 Filter Plugin" to request a proposed canonical name as part of the submission. - Adds "Updating an existing registration for v3" with the three-step task list for current plugin maintainers. Existing plugin builds are unaffected; canonical names only become load-bearing when a plugin opts into H5Z_class3_t. Maintainer confirmations are tracked in HDFGroup#255. See RFC-HDFG-2026-001 for the v3 design.
brtnfld
requested review from
ajelenak,
bmribler,
fortnern,
glennsong09,
jhendersonHDF,
lrknox and
mattjala
as code owners
This was referenced May 15, 2026
"HDF5 v3" reads as "HDF5 library 3.0", but the new plugin class
H5Z_class3_t ships in HDF5 2.x. Rename the section heading, the
subsection on updating existing registrations, and replace
"v3-aware library" / "v3 build" / "HDF5 v3 plugin" wording with
direct references to H5Z_class3_t or "HDF5 2.x" as appropriate.
The plugin-class version ("v3", as in v1/v2/v3 of H5Z_class_t) is
retained only where the versioning of the class itself is the
subject.
brtnfld
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
proposed names marked
(proposed)pending maintainer confirmation.H5Z_class3_tplugin class)" section documenting thesyntactic rules, allocation policy (first-registered-wins), and the
self-namespacing convention for unregistered plugins.
registration for
H5Z_class3_t" subsection for current maintainers.Why
HDF5 2.x introduces a new filter plugin class,
H5Z_class3_t, that strengthensthe contract on the
namefield: in anH5Z_class3_tplugin it is no longer afree-form debug comment but a stable string identifier used by the new
H5Pappend_filterAPI, written into the on-disk filter-pipeline message atfilter-add time, and shown by
h5dump/h5repack. Today the registry records(id, label, description, contact)but no normative canonical-name string —this PR closes that gap.
Existing plugin builds are unaffected; canonical names only become load-bearing
when a plugin opts into the
H5Z_class3_tclass.See RFC-HDFG-2026-001 for the full design.
Maintainer confirmation
Tracking issue: #255. Maintainers of currently registered plugins are asked to
reply on that issue with an explicit
Confirm: ID X, canonical name \foo`.(orCorrection: ...) line. Confirmed rows lose the(proposed)` marker infollow-up PRs.
Where to comment: confirmations of a proposed canonical name belong on
issue #255 (not on this PR — comments here are for review of the doc edit
itself, and confirmations would get lost during code review). Feedback on
the doc wording, the section structure, or the syntactic rules belongs on
this PR.
Out of scope
HDFGroup/hdf5#6407.
Test plan
(proposed)markers, link to Canonical name confirmation for H5Z_class3_t filter plugins #255).#canonical-names-h5z_class3_t-plugin-classresolves.