This metadata-docs/ directory contains metadata technical documentation and specifications that don't fit in the existing codebase documentation methods, but require management, a review process, and versioning beyond what is captured in the GitHub wiki. In particular, when a Hyrax version is released, the metadata-docs/ travel with the codebase and indicate the current metadata specifications followed in that release. This documentation doesn't indicate recommendations for individual implementations of Hyrax (your metadata documentation will no doubt vary), but aims to clarify what metadata specifications exist in the core Hyrax codebase.
It is not intended to be a space for auto-generated docs based off of the code (i.e., this is not attached to something like Rdoc), nor is it necessarily limited to plain text markdown files (though files with proprietary formats are to be avoided). However, it should be metadata documentation and specifications that are (or need to be) more closely coupled with the codebase itself and version releases. Other documentation should use the existing GitHub Wiki for the Hyrax Repository.
The update and review procedure for the documentation in metadata-docs/ is proposed as follows:
- Discussion: Questions, Requests for Changes, or Issues are discussed using GH Issues on the Hyrax Repository tagged 'metadata' and including the Hyrax-Metadataist Team as reviewers. This triggers Hyrax Metadataist Team volunteers to set up a timeframe & channel of communication for the requested input/review. They should also clarify the needed output from this discussion, as well as manage generating the output or kicking to a further working group as needed.
- Proposal: A Proposal for update of the relevant documentation is created and either attached to a current branch with the code changes that led to the documentation update, or attached to it's own branch if not directly attached to code changes (see below for more on this).
- PR Review: The branch with the metadata-docs/ changes is part of an issued PR, including the existing review structure of the changes there. This includes checking the documentation / codebase relationship (described below).
- Merge: Once accepted, the PR is merged into the core Hyrax codebase master (or appropriate) branch.
Additionally, under the charge of the management of the Hyrax-Metadataist Team, an annual full-pass review of metadata-docs/ for needed updates, checking on stalled discussions and outputs, or other general maintenance issues should be performed.
For metadata-docs/ to remain relevant and in sync with the code, there needs to be a two-way review process between codebase / code changes and docs or metadata specification changes.
PRs and Release reviews should include a metadata-docs/ review (reviewers for this would be pulled from the Hyrax-Metadataist Team for the metadata specifications). This ensures the metadata-docs/ documentation is relevant to that codebase release or change.
Specific questions or issues that pertain to the metadata-docs/ or the related work perhaps not yet captured there can be brought to discussion using GH Issues on the Hyrax Repository tagged 'metadata' and including the Hyrax-Metadataist Team as reviewers. The output of those discussions, where appropriate, should fall back into the metadata-docs/ Update Procedure, above.
Contact:
- Hyrax-Metadataist Team,
- Project Hydra Slack Channel for #metadata,
- Or the Hydra-tech list.
For help with git / GitHub to work with these specifications, we recommend an introduction to the GitHub flow and simple steps for getting started in GitHub.
That said, git (a version control system) and GitHub (a place to host git repositories) are used to coordinate the above metadata procedures and documentation within a community, and our Hyrax community has many folks with git/Github experience willing to help, as well as plenty of work or discussion paths that don't require git knowledge to participate.
