Zum Hauptinhalt springen

Contribute

Use this page when you need to change the Helpifyr public docs or related source truth in a way that stays owner-clear, reviewable, and verifiable.

When to use this page​

  • You are preparing a docs or public-surface change.
  • You need to understand issue, review, and verification expectations.
  • You need to contribute without breaking provenance or publication safety.

Prerequisites​

  • You know which repo owns the source of the change.
  • You understand the difference between source truth, reviewed materialization, and live publication.

Contribution model​

Documentation changes should be:

  • issue-driven
  • owner-reviewed
  • tied to the correct source repo
  • verified before being treated as publication truth

Architecture / Flow​

Step-by-step procedure​

1. Start with ownership​

Typical split:

  • source truth or product contract:
    • owner repo such as helpifyr-fabric
  • reviewed public docs materialization:
    • jhf-docs
  • live public publication:
    • jhf-web

2. Keep an issue trail​

Public surface changes should be easy to trace back to:

  • the reason for the change
  • the owner repo
  • the review and verification evidence

Cross-repo docs should prefer logical or canonical targets over fragile local assumptions.

4. Verify before claiming publication truth​

For jhf-docs, the standard sequence is:

python scripts/materialize_public_docs_site.py
python scripts/materialize_public_docs_site.py --check
npm run build --prefix docs-site

5. Distinguish local success from live publication​

A green local build is not the same as live truth. Publication claims require the reviewed artifact and live readback to align.

Verification​

This page is being applied correctly when:

  1. the change is made in the correct owner lane
  2. review and issue traceability are preserved
  3. local verification and publication readback are not confused

Common failure modes​

Editing only the materialized output when the source lives elsewhere​

Problem:

  • the visible symptom changes but the source truth remains wrong.

Better path:

  • fix the correct owner lane or explicit override lane

Calling a local build “published”​

Problem:

  • readers assume live truth changed when only local artifacts did.

Better path:

  • require reviewed-artifact and live-site readback for publication claims

Source Truth​

Next paths​