docs(contribute): add the codebase overview from #1824 - #8407
Merged
Merged
Conversation
Issue #1824 asked for two things in 2018: a contributing section in the docs and a codebase overview. The section has existed for years; the overview was never written, so nothing on the site tells a would-be contributor how webpack's own source is laid out, and the site never linked to CONTRIBUTING.md or TESTING_DOCS.md at all. Adds a page mapping the five objects a build runs through, the three phases, what each lib/ directory holds, and how to find the code behind an option, a hook, a runtime symbol or an error. It links out to CONTRIBUTING.md and TESTING_DOCS.md for process and tests rather than restating them, which is what the issue thread asked for.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
This branch was successfully deployed
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
1 participant
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.
Summary
#1824 asked for two things back in 2018. Checking both against the site today:
/contribute/has seven pages, andWriting a Loader,Writing a Plugin,Plugin Patterns,Debugging,Release Processand theWriter's Guidecover extending webpack and the project's process.CONTRIBUTING.md(94 lines: issues, setup, submitting changes, releases, types) has no architecture section either. So a contributor who wants to changelib/has nowhere to start.This adds that page. Refs #1824 — the second box, and it is the last one open.
On not duplicating, which the thread was explicit about: skipjack asked that the pages live in the existing Contribute section and that
CONTRIBUTING.mdnot be restated. So the page covers only the source layout, and hands off for everything else — process to CONTRIBUTING.md, tests to TESTING_DOCS.md, hooks to the existing/api/compiler-hooks/and/api/compilation-hooks/, and writing loaders and plugins to the pages that already do that. AT>at the top says which audience it is for, since "contributing to webpack" and "extending webpack" get mixed up constantly.Worth noting separately: the site linked to neither
CONTRIBUTING.mdnorTESTING_DOCS.mdfrom anywhere./contribute/now does.Contents: the five objects a build runs through (
Compiler,Compilation,Module,Dependency,Chunk) with a link to each file; the make / seal / emit phases with the method that starts each; a table of what everylib/directory holds; and four recipes for finding the code behind a configuration option, a hook, a runtime symbol, or an error message.Checked against the repository rather than written from memory: each file and directory named exists on
maintoday, thelib/grouping was built from the actual 38 subdirectories, and the entry points quoted are real (Compiler#compile,Compilation#seal,Compiler#emitAssets).What kind of change does this PR introduce?
docs
Did you add tests for your changes?
n/a — documentation only.
Does this PR introduce a breaking change?
No — one new page plus two lines on
/contribute/.If relevant, what needs to be documented once your changes are merged or what have you already documented?
n/a. If you want to follow the thread's other suggestion,
CONTRIBUTING.mdcould later link here instead of growing an architecture section of its own.Use of AI
AI was used. Claude Code checked what
/contribute/andCONTRIBUTING.mdalready cover so the page would not repeat them, verified every file, directory and entry point it names against the webpack repository, and drafted the page; I reviewed it before pushing.Generated by Claude Code