diff --git a/.github/ISSUE_TEMPLATE/1-bug-report.yml b/.github/ISSUE_TEMPLATE/1-bug-report.yml new file mode 100644 index 00000000..a6e3ad89 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/1-bug-report.yml @@ -0,0 +1,76 @@ +name: πŸ› Bug Report +description: Report a problem with the documentation site or its build tooling +labels: [bug] +body: + - type: markdown + attributes: + value: | + Thank you for reporting a bug! Before submitting, make sure this is the right repository: + + - **This repository** β€” documentation content, generated API docs, build scripts, TypeDoc plugins, and the site theme. + - **[nodejs/doc-kit](https://github.com/nodejs/doc-kit/issues)** β€” bugs in the underlying Markdown-to-HTML engine (parsing, core rendering). This site uses doc-kit with a custom theme, so visual issues usually belong *here*; engine issues belong there. + - **[webpack/webpack](https://github.com/webpack/webpack/issues)** β€” bugs in webpack itself. + + When in doubt, file it here and we'll move it. Also search existing issues to avoid duplicates. + + - type: dropdown + id: area + attributes: + label: Which area is affected? + options: + - Documentation content (pages/) + - Generated API docs (TypeDoc output) + - Build tooling (scripts, plugins) + - Theme / visual appearance + - Not sure + validations: + required: true + + - type: textarea + id: description + attributes: + label: Bug description + description: A clear and concise description of what the bug is. + placeholder: When I do X, Y happens instead of Z. + validations: + required: true + + - type: textarea + id: reproduction + attributes: + label: Steps to reproduce + description: For site issues, include the affected page URL. For build issues, include the command you ran and its output. + placeholder: | + 1. Go to https://webpack.js.org/... + 2. ... + + OR + + 1. Run `npm run build` + 2. See error + validations: + required: true + + - type: textarea + id: expected + attributes: + label: Expected behavior + description: What did you expect to happen instead? + + - type: input + id: environment + attributes: + label: Environment + description: For build issues β€” your Node.js version, npm version, and OS. + placeholder: Node.js 24.x, npm 11.x, macOS 15 + + - type: dropdown + id: ai + attributes: + label: Have you used AI? + description: If you used AI tooling to generate this issue, please state so per webpack's [AI policy](https://github.com/webpack/governance/blob/main/AI_POLICY.md). + options: + - 'No' + - 'Yes' + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/2-content-issue.yml b/.github/ISSUE_TEMPLATE/2-content-issue.yml new file mode 100644 index 00000000..9558b3b1 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/2-content-issue.yml @@ -0,0 +1,46 @@ +name: πŸ“ Documentation Content Issue +description: Report incorrect, outdated, or missing documentation content +labels: [documentation] +body: + - type: markdown + attributes: + value: | + Thank you for helping improve the webpack docs! A few notes on where content comes from: + + - Guides, concepts, and blog posts live in `pages/` in this repository β€” report (or fix!) them here. + - **API docs** (`/docs/api/`) are generated from webpack's `types.d.ts` β€” inaccuracies in type descriptions may need fixing in [webpack/webpack](https://github.com/webpack/webpack), while formatting/generation problems belong here. + - **Loader and plugin pages** are generated from the READMEs of their respective repositories. + + - type: input + id: page + attributes: + label: Affected page + description: URL or file path of the page with the problem. + placeholder: https://webpack.js.org/docs/... or pages/guides/... + validations: + required: true + + - type: textarea + id: problem + attributes: + label: What is wrong? + description: Describe what is incorrect, outdated, unclear, or missing. + validations: + required: true + + - type: textarea + id: suggestion + attributes: + label: Suggested fix + description: If you know what the content should say, tell us β€” or consider opening a pull request! + + - type: dropdown + id: ai + attributes: + label: Have you used AI? + description: If you used AI tooling to generate this issue, please state so per webpack's [AI policy](https://github.com/webpack/governance/blob/main/AI_POLICY.md). + options: + - 'No' + - 'Yes' + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/3-feature-request.yml b/.github/ISSUE_TEMPLATE/3-feature-request.yml new file mode 100644 index 00000000..acda0a9f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/3-feature-request.yml @@ -0,0 +1,41 @@ +name: πŸš€ Feature Request +description: Suggest an improvement to the documentation site or its tooling +labels: [enhancement] +body: + - type: markdown + attributes: + value: | + Thanks for the suggestion! Note that feature requests for the underlying Markdown-to-HTML engine belong in [nodejs/doc-kit](https://github.com/nodejs/doc-kit/issues), and feature requests for webpack itself belong in [webpack/webpack](https://github.com/webpack/webpack/issues). + + - type: textarea + id: problem + attributes: + label: What problem does this solve? + description: Describe the problem or limitation you are running into. + validations: + required: true + + - type: textarea + id: solution + attributes: + label: Proposed solution + description: Describe what you would like to happen. + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: Any alternative solutions or workarounds you have considered. + + - type: dropdown + id: ai + attributes: + label: Have you used AI? + description: If you used AI tooling to generate this issue, please state so per webpack's [AI policy](https://github.com/webpack/governance/blob/main/AI_POLICY.md). + options: + - 'No' + - 'Yes' + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..096ed805 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,13 @@ +contact_links: + - name: πŸ”§ Bug in the doc-kit rendering engine + url: https://github.com/nodejs/doc-kit/issues + about: Problems with the Markdown-to-HTML engine itself (parsing, core rendering) belong in nodejs/doc-kit. Site-specific theme and content issues belong here. + - name: πŸ“¦ Bug or feature request for webpack itself + url: https://github.com/webpack/webpack/issues/new/choose + about: Issues with webpack's behavior β€” not its documentation β€” belong in webpack/webpack. + - name: πŸ’¬ Questions and help + url: https://github.com/orgs/webpack/discussions + about: Ask questions and get help from the webpack community. + - name: πŸ”’ Report a security vulnerability + url: https://github.com/webpack/.github/blob/main/.github/SECURITY.md + about: Please report security issues privately following our security policy β€” never in a public issue. diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 00000000..e0410bde --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,26 @@ +version: 2 +updates: + - package-ecosystem: npm + directory: / + schedule: + interval: weekly + open-pull-requests-limit: 10 + commit-message: + prefix: chore(deps) + groups: + minor-and-patch: + applies-to: version-updates + update-types: + - minor + - patch + + - package-ecosystem: github-actions + directory: / + schedule: + interval: weekly + commit-message: + prefix: chore(ci) + groups: + actions: + patterns: + - '*' diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..f3d5e3af --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,75 @@ +# Contributing to webpack.js.org + +Welcome, and thank you for helping improve webpack's documentation! This repository holds the hand-written content and the build tooling behind [webpack.js.org](https://webpack.js.org). + +We hope this guide helps you find the right kind of contribution and get productive quickly, however, you should also check out other guide-like resources in this repository: + +- The [Writer's Guide](pages/guides/contributing/writers-guide.md) +- The [README](README.md) +- webpack's [AI policy](https://github.com/webpack/governance/blob/main/AI_POLICY.md) + +## Does your change belong here? + +The website assembles content from several sources, so the first step is confirming you are in the right place: + +| You want to change… | Go to… | +| ---------------------------------------------------------- | ------------------------------------------------------------ | +| Guides, blog posts, or other hand-written pages (`pages/`) | **This repository** | +| The build tooling, API doc generation, or site theme | **This repository** | +| Generated API reference pages (`/docs/api/`) | [webpack/webpack](https://github.com/webpack/webpack) | +| Loader or plugin reference pages | The README of that loader or plugin's repository | +| The Markdown-to-HTML engine itself | [nodejs/doc-kit](https://github.com/nodejs/doc-kit) | +| webpack's actual behavior | [webpack/webpack](https://github.com/webpack/webpack/issues) | + +When in doubt, [ask in the webpack Discord](https://discord.com/invite/webpack) and we will point you in the right direction. + +## Writing and improving documentation + +**Read the [Writer's Guide](pages/guides/contributing/writers-guide.md).** + +If you want to write something but don't know what, look through [open issues](https://github.com/webpack/webpack.js.org/issues) labeled `documentation`, or start a discussion proposing the topic before investing significant writing time. + +## Working on the tooling + +The generator code lives in `scripts/` (pipeline stages) and `plugins/` (TypeDoc processing and the doc-kit theme). Start with the [README](README.md) β€” it explains the three-stage pipeline (prepare β†’ Markdown β†’ HTML) and what each script does. + +The site is built on [@node-core/doc-kit](https://github.com/nodejs/doc-kit). Improvements to the engine itself (Markdown parsing, core rendering) belong upstream; the theme and plugins in this repository customize it for webpack. + +## Local development + +You need the latest LTS release of [Node.js](https://nodejs.org) (CI uses `lts/*`) and npm. + +```sh +git clone https://github.com//webpack.js.org.git +cd webpack.js.org +npm ci +npm run build +``` + +In the above example, `npm run build` runs the whole pipeline (it downloads the webpack releases in `versions.json` and generates their API docs), so it takes a few minutes. After that, if you are only editing hand-written pages, regenerate just the HTML: + +```sh +npm run build:html +``` + +The site is written to `out/` with absolute URLs that expect `http://localhost:3000`, so serve it on that port: + +```sh +npx serve out -l 3000 # Port 3000 is default, but it never hurts to be explicit. +``` + +## Opening a pull request + +1. Create a branch on your fork, and try to keep each pull request focused on one change. +2. Follow [Conventional Commits](https://www.conventionalcommits.org/) for commit messages (`feat:`, `fix:`, `docs:`, `chore:`…). +3. A pre-commit hook formats and lints staged files. You can run the same checks yourself with `npm run lint` and `npm run format:check`. +4. If you used AI tooling, read and follow the [AI policy](https://github.com/webpack/governance/blob/main/AI_POLICY.md). +5. A maintainer will review your pull request after it is opened. + +## Code of Conduct + +This project follows the [OpenJS Foundation Code of Conduct](https://code-of-conduct.openjsf.org). Be kind, be patient, and assume good intent. + +## Licensing + +Code in this repository is licensed under [MIT](LICENSE). Documentation content in `pages/` is available under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), consistent with webpack.js.org. By contributing, you agree that your contributions are licensed under these terms. diff --git a/LICENSE b/LICENSE new file mode 100644 index 00000000..aa55b474 --- /dev/null +++ b/LICENSE @@ -0,0 +1,20 @@ +Copyright Webpack contributors + +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +'Software'), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE +LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION +WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/README.md b/README.md index 235d695d..b296194a 100644 --- a/README.md +++ b/README.md @@ -57,8 +57,10 @@ node scripts/markdown/index.mjs .cache/webpack/v5.107.1 ## Contributing +See the [contributing guide](CONTRIBUTING.md) for setup instructions, project conventions, and guidance on where issues belong (this repository, [doc-kit](https://github.com/nodejs/doc-kit), or [webpack](https://github.com/webpack/webpack)). + When making changes to documentation generation (plugins, `scripts/markdown/index.mjs`, `tsconfig.json`), ensure the docs can still be generated successfully. CI will verify this on every pull request. ## License -See the [webpack project](https://github.com/webpack/webpack) for license details. +Code in this repository is licensed under [MIT](LICENSE). Documentation content in `pages/` is available under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), consistent with webpack.js.org.