docs(engineering): add process docs and stacked-PR learnings - #51
Merged
Conversation
…stacked-PR learnings Three process docs under docs/internal/engineering/process/, each tuned to a persona: - implementing-an-issue.md — dev's playbook (read issue, branch, code, changesets, push, PR). Companion for anyone picking up an issue. - releasing-a-new-version.md — release engineer's playbook (build the release branch, cherry-pick, push, watch the workflow, verify artifacts). Mirrors the conventions we hardened in PRs #39-47. - pr-authoring.md — standards for the body of a PR (six canonical sections, mandatory code sample when public API changes, before/after default, after-only when purely additive). Enforces what PR #50 demonstrated: documented the .addNote() worked-example as the in-doc template. Also adds docs/learnings/github/stacked-pr/README.md, notes captured during PR #39-43 setup around how stacked PRs work in GitHub and how they apply to a release branch. No code, no workflow changes. Documentation only.
- Prettier auto-formatted two of the four process docs (markdown table alignment in pr-authoring.md, bullet spacing in implementing-an-issue.md). - Add a no-op changeset so the ci.yml lint passes. The lint currently requires a changeset on every PR to staging regardless of path; this is a known limitation tracked in the release-system plan Section 4. A future change can implement the documented exemption for docs-only and CI-only PRs.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds four documentation files, no code or workflow changes.
What this PR adds
Three process docs under
docs/internal/engineering/process/:implementing-an-issue.md— the dev's playbook: read the issue, branch fromstaging, code, add a changeset, push, open the PR. Covers the full dev flow including hotfixes.releasing-a-new-version.md— the release engineer's playbook: build the release branch, cherry-pick the batch, push, watch the workflow, verify the artifacts. Mirrors the conventions we hardened in PRs docs(release): add release system plan #39-47.pr-authoring.md— standards for the body of a PR: six canonical sections (## Summary,## Why,## What changed,## Code sample,## Verified locally,## Risk), mandatory code sample when public API changes, before/after default, after-only acceptable when the change is purely additive. The worked example in this doc is the .addNote() PR body we shipped in feat(errors): implement ErrorInstance.addNote() #50.Plus one learning file:
docs/learnings/github/stacked-pr/README.md— notes captured during PR docs(release): add release system plan #39-43 setup around how stacked PRs work in GitHub and how the pattern applies to a release branch.Why
These docs capture what we demonstrated through the work. PR #50 was the first to follow
pr-authoring.md— the body has a## Code samplebefore/after. PR #44 followedreleasing-a-new-version.mdin spirit and surfaced the recovery lessons documented there (ENEDAUTH, E422, tag drift,git diff --cached).implementing-an-issue.mdis the dev-side mirror of the release process doc.Until now, the process was implicit. Having it written down saves new contributors and future AI assistants from rediscovering the conventions.
How to read these
implementing-an-issue.md, finish withpr-authoring.md.releasing-a-new-version.mdbefore running anything.learnings/github/stacked-pr/README.mdcaptures the GitHub concept with a worked example.Risk
None. Documentation only. No code, no workflow changes, no
.changeset/*.mdrequired (per the documented docs exemption in CONTRIBUTING.md and ci.yml).Verification
pnpm format:checkwould have auto-reformatted the files on commit; manual review confirms consistent headings and bullet style with the rest ofdocs/internal/engineering/.