Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
45 lines (33 loc) · 1.54 KB

CONTRIBUTING.md

File metadata and controls

45 lines (33 loc) · 1.54 KB
Raw

Contributing to MAF

Thanks for improving MAF.

Source of Truth

  • taxonomy/ is the source of truth.
  • dist/MAF-taxonomy.md and dist/MAF-taxonomy.json are generated artifacts.
  • Do not manually edit dist/ in pull requests.

Contribution Flow

  1. Edit source files (taxonomy/, guides, schemas, tooling) as needed.
  2. Run local checks:
    • python tools/validate.py
    • python tools/lint-links.py
    • python tools/build.py
  3. Open a PR with a declared change type.
  4. Do not include manual changes under dist/.

Change Types

Declare one primary change type in every PR:

  • editorial: wording changes only, no semantic effect.
  • clarification: improves class boundaries, intent, or examples without changing class meaning.
  • semantic: changes definition, failure mechanism, or class boundary meaning.
  • structural: adds/removes/renames categories, classes, or taxonomy structure.

PR Requirements

  • Edit source files under taxonomy/ for taxonomy updates.
  • Preserve required section headers in every taxonomy class file.
  • Keep id stable unless deprecating/replacing with migration context.
  • Update related links when boundaries change.
  • Update Do not classify here if when semantic boundaries change.
  • Add migration/deprecation note when ID/title changes affect consumers.
  • Ensure validation and build tooling pass locally.

ID Stability

  • Never reuse retired IDs.
  • After v1.0, deprecate instead of deleting.
  • Deprecated IDs must remain documented.
  • External reports and integrations may depend on ID stability.