[Feature]: Reviewable Requirements and Design Documentation #35
Description
Problem Statement
Proper review-sets involve having the requirements and design documentation being included with the code and tests for each conceptual group.
Proposed Solution
Read https://github.com/demaconsulting/ContinuousCompliance/blob/copilot/expand-reviewmark-assistance-ai/docs/file-reviews.md for documentation about good review-set practices.
The https://github.com/demaconsulting/TestResults project demonstrates a project with reviewable requirements and design documentation.
The conceptual groups of VersionMark seem to be:
- Command Line (Program and Context)
- Utilities (PathHelpers, MarkdownFormatter)
- Configuration (VersionMarkConfig)
- Version Information (VersionInfo)
- Self-Validation (Validation)
Ensure the conceptual groups make sense, then:
- Split the ReqStream requirements for each conceptual group into separate files in docs/reqstream folder (see TestResults for an example) - note that some conceptual groups may not have requirements if the functionality is completely internal
- Create a docs/design folder with separate markdown files for each conceptual group (see TestResults for an example)
- Update the .reviewmark.yaml (again see TestResults for an example) populating the file list with requirements, design, sources, and tests (note that all test files must be reviewed - find the most appropriate review-set)
Additionally note that the TestResults repo splits the platform/runtime and ots-software requirements into their own reqstream yaml files in the docs/reqstream folder, so the root requirements.yaml just contains includes.
Additionally the design document should be compiled to PDF and included in the documents artifact.
Alternatives Considered
No response
Usage Examples
Benefits
Creating review-sets like this assists in AI agent reviews and makes the project formally reviewable.
Priority
High - Blocking my use case
Willingness to Contribute
Yes, I can submit a pull request
Additional Context
No response
Checklist
- I have searched existing issues to ensure this is not a duplicate
- I have provided a clear description of the feature
- I have explained why this feature would be useful