docs: add canonical name column to registered filter plugins (HDF5 v3)#256
Open
brtnfld wants to merge 1 commit into
Open
docs: add canonical name column to registered filter plugins (HDF5 v3)#256brtnfld wants to merge 1 commit into
brtnfld wants to merge 1 commit 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
35 tasks
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_t)" section documenting thesyntactic rules, allocation policy (first-registered-wins), and the
self-namespacing convention for unregistered plugins.
registration for v3" subsection for current maintainers.
Why
HDF5 2.x introduces
H5Z_class3_t, which strengthens the contract onH5Z_class_t::name: in v3 plugins the field is no longer a free-form debugcomment but a stable string identifier used by the new
H5Pappend_filterAPI,written into the on-disk filter-pipeline message at filter-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 v3 (
H5Z_class3_t) class.See RFC-HDFG-2026-001 for the full v3 design.
Maintainer confirmation
Tracking issue: #255. Maintainers of currently registered plugins are asked to
👍 or ✏️ the proposed canonical name for their filter ID. Confirmed
rows lose the
(proposed)marker in follow-up PRs.Out of scope
HDFGroup/hdf5#6407.
Test plan
(proposed)markers, link to Canonical name confirmation for HDF5 v3 (H5Z_class3_t) plugins #255).#canonical-names-hdf5-v3--h5z_class3_tresolves.