Problem Statement
The current requirements are limited to publicly visible functionality, leaving internal helper classes lacking requirements.
Proposed Solution
A new requirements parent section "Internal Functionality" should be created, with sub-sections for all classes containing the functional specifications (internal requirements) for those classes.
The docs/reqstream folder should therefore contain files falling into two categories:
- Public Concepts (command-line, reports, platform, ots-software)
- Classes (program, context, path-helpers, markdown-formatter, etc.)
The Public concepts should have a "public" tag, and the classes should have an "internal" tag.
To match this, the docs/design should also have a similar two-category layout:
- Public Concept markdown files (command-line, reports, platform)
- Class markdown files - one for each class
The review-sets should be adjusted so each public concept and each class is reviewed in isolation. This will result in some files getting reviewed multiple times, but that's fine. The requirements at the class level can contain justification comments explaining why each function is required, and that requirements file may optionally be included in reviews of user-code so those reviews can see what's available.
This is an extensive change to the requirements, documentation, and review-sets.
Alternatives Considered
No response
Usage Examples
Benefits
This should result in more review-sets; but those review sets should be targeted on smaller items and each one should have requirements/functional-specifications, design-documentation, code, and tests. As a result the reviews should be more focused on the functionality being reviewed to ensure accuracy and completeness.
Priority
Medium - Would improve my workflow
Willingness to Contribute
Yes, I can submit a pull request
Additional Context
No response
Checklist
Problem Statement
The current requirements are limited to publicly visible functionality, leaving internal helper classes lacking requirements.
Proposed Solution
A new requirements parent section "Internal Functionality" should be created, with sub-sections for all classes containing the functional specifications (internal requirements) for those classes.
The docs/reqstream folder should therefore contain files falling into two categories:
The Public concepts should have a "public" tag, and the classes should have an "internal" tag.
To match this, the docs/design should also have a similar two-category layout:
The review-sets should be adjusted so each public concept and each class is reviewed in isolation. This will result in some files getting reviewed multiple times, but that's fine. The requirements at the class level can contain justification comments explaining why each function is required, and that requirements file may optionally be included in reviews of user-code so those reviews can see what's available.
This is an extensive change to the requirements, documentation, and review-sets.
Alternatives Considered
No response
Usage Examples
Benefits
This should result in more review-sets; but those review sets should be targeted on smaller items and each one should have requirements/functional-specifications, design-documentation, code, and tests. As a result the reviews should be more focused on the functionality being reviewed to ensure accuracy and completeness.
Priority
Medium - Would improve my workflow
Willingness to Contribute
Yes, I can submit a pull request
Additional Context
No response
Checklist