Skip to content

[P2][Ecosystem] Standardize Features documentation template for vcpkg ports #603

Description

@kcenon

What

Define and pilot a standard "Features" documentation section template for all kcenon ecosystem READMEs. The template should clearly enumerate vcpkg features with:

  • Feature name
  • Default on/off state
  • What it enables functionally
  • Transitive dependencies pulled in when the feature is selected
  • Mutually exclusive or prerequisite features

Pilot the template in kcenon/pacs_system (which has the most complex feature matrix at 7 features: storage, codecs, ssl, aws, azure, rest-api, testing), then apply the refined template to the other seven repos.

Why

During the vcpkg readiness analysis, multiple repos scored below the maximum purely because users had no way to decide which features to enable. The vcpkg.json files themselves are technically complete, but they force users to read source code to understand what [ssl,aws,rest-api] actually does.

This is a documentation-only fix with high leverage: a single template reused across eight repos immediately raises the user-facing quality of the entire ecosystem. It also establishes a convention that future additions must follow, preventing per-repo drift.

Where

  • Template location: docs/FEATURES_TEMPLATE.md in this repository (kcenon/common_system)
  • Pilot target: kcenon/pacs_system README.md — add a "## Features" section
  • Rollout targets: Each of the other seven ecosystem repos — tracked as follow-up sub-issues linked from this one

How

Template Structure

## Features

\`\`\`bash
vcpkg install <port-name>[feature1,feature2,...]
\`\`\`

| Feature | Default | Description | Pulls In | Prerequisites |
|---------|:-------:|-------------|----------|---------------|
| ssl     |   on    | Enables TLS via OpenSSL        | openssl      ||
| aws     |   off   | AWS S3 object storage backend  | aws-sdk-cpp  | storage |
| testing |   off   | GoogleTest-based unit tests    | gtest        ||

### Feature Selection Guidance

- **Minimal install**: \`vcpkg install <port-name>\`
- **Production with TLS**: \`vcpkg install <port-name>[ssl]\`
- **Cloud deployment**: \`vcpkg install <port-name>[ssl,aws]\`

Pilot and Rollout Plan

  1. Write the template in common_system/docs/FEATURES_TEMPLATE.md
  2. Apply it to pacs_system/README.md (stress test — 7 features)
  3. Review: does the template scale? Does it read clearly? Adjust template based on pilot experience
  4. Create follow-up issues in each of the other seven repos referencing the finalized template
  5. Close this issue when the template is stable and the pilot is merged

Acceptance Criteria

  • docs/FEATURES_TEMPLATE.md committed to common_system with rationale
  • pacs_system README has a Features section that follows the template
  • Follow-up issues opened in the other seven ecosystem repos
  • Template is referenced from the main ecosystem README / ECOSYSTEM.md

Scope Boundary

This issue ends at the pilot (template + pacs_system application). Per-repo adoption is tracked as separate issues, each owned by that repo's maintainer.

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentation

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions