Skip to main content

Contribute to the Stack

Use this page when your first job is to change Helpifyr documentation, contracts, or another public surface in a way that stays owner-clear, reviewable, and verifiable.

When to use this page​

  • You need a contributor-first path instead of an operator or integrator path.
  • You are changing docs, contracts, generated publication surfaces, or public-safe examples.
  • You need to know which repo owns the change and how publication truth is verified afterward.

Prerequisites​

  • You know whether the change belongs to an owner repo, jhf-docs, or jhf-web.
  • You are ready to keep issue trail, review, and verification evidence together.

Architecture / Flow​

Step-by-step procedure​

1. Identify the true owner lane​

Typical split:

  • source truth or product contract:
    • owner repo such as helpifyr-fabric
  • reviewed public-docs materialization:
    • jhf-docs
  • live public publication:
    • jhf-docs
  • main-site shell, alias, or handoff consumption:
    • jhf-web

2. Decide whether this is source truth or a public-safe override​

Use source-owner repos for:

  • product contracts
  • versioned product docs truth
  • route or behavior claims that come from the product itself

Use the jhf-docs override lane for:

  • public-safe longform guidance that the generated bundle does not yet provide
  • curated hub and journey pages
  • cross-area connective documentation with explicit owner handoffs

3. Keep the issue and review trail explicit​

A good contribution should be traceable to:

  • the reason for the change
  • the owner repo or override lane
  • the verification evidence

4. Verify locally before you claim anything about publication​

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 reviewed artifact truth from live-site truth​

Local success means the reviewed artifact is internally consistent. It does not by itself prove that the live site is updated. That final claim requires publication and live readback.

Verification​

This contributor path is being followed correctly when:

  1. the change is made in the correct owner lane
  2. the local verification sequence is green
  3. reviewed artifact and live publication are not conflated

Common failure modes​

Editing the materialized output instead of the source or override lane​

Problem:

  • the visible change will be overwritten by the next materialization.

Better path:

  • edit the true source owner or the explicit docs/public-docs-overrides/** lane

Calling a green local build “published”​

Problem:

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

Better path:

  • require reviewed-artifact and live-site readback before making a publication claim

Source Truth​

Next paths​