Skip to content

[Docs] Separate maintainer procedures from developer onboarding #776

Description

@divyarajmasani

Parent epic: #768 — Documentation epic

Base branch: theme-elementary-v2. Cover its functionality and subsequent changes based on it. Verify against the latest relevant v2 implementation and record the tested commit in the documentation PR.

Problem and scope

Pilot workarounds and dependency-development procedures obscure normal setup and can become stale. Create a small docs/internal/ area and migrate relevant material from docs/internal-testing.md.

Proposed structure

Start with two documents; split further only when the content warrants it:

  • docs/internal/README.md: audience, supported revisions, index, and status of temporary procedures.
  • docs/internal/maintenance.md: release validation and local dependency development.

Link to existing knowledge-graph guidance. Move or split graph maintenance details only where necessary; keep instructions needed by downstream developers discoverable.

Maintenance guide contents

  1. Release validation: test the advertised installation paths, initialization, representative example removal/feature toggles, local startup, builds, and checks.
  2. Cleanup validation: verify actual retained files and documentation links; report broken scripts or removed capabilities as implementation issues.
  3. Local dependency development: sibling wp-framework/wp-tooling setup, local source overrides, and restoring only those overrides while retaining theme identity changes.
  4. Temporary pilot procedures: why each is needed, applicable revision/date, and an explicit retirement condition.
  5. Documentation validation: record journey and link-check results; link CI automation work separately if required.

Acceptance criteria

  • Normal onboarding contains no maintainer-only dependency workaround.
  • Internal guidance identifies its audience and applicable revision.
  • Existing internal-testing instructions are reconciled with current package resolution and links updated.
  • Temporary procedures have removal conditions.
  • Maintainers can repeat the advertised developer journeys and record results.
  • Cleanup/tooling fixes and new CI automation are separate linked implementation tasks.
  • CONTRIBUTING links to the internal index; the main onboarding route stays concise.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

DocumentationinternalInternal development and pilot proceduresmaintainerRepository maintenance and release procedures

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions