From 04f2328c7cf0d7761ff129ce9873d8df4c0edf27 Mon Sep 17 00:00:00 2001 From: Hannah Wolfe Date: Sun, 16 Aug 2026 17:32:36 +0100 Subject: [PATCH 1/2] Added Node.js compatibility reference (#30000) Migrated the ghost / ghost-cli / node compatibility table into the codebase documentation. This is part of work to bring codebase docs into the codebase, and make sure the information is consistent, correct and coherent. --- docs/README.md | 5 ++ docs/contributing/development-setup.md | 3 + docs/reference/node-compatibility.md | 81 ++++++++++++++++++++++++++ 3 files changed, 89 insertions(+) create mode 100644 docs/reference/node-compatibility.md diff --git a/docs/README.md b/docs/README.md index e61aeb2796f..8ec0f0afaaa 100644 --- a/docs/README.md +++ b/docs/README.md @@ -95,6 +95,11 @@ Practice and contributor guides explain how to make and verify changes: - [Internationalization](practices/internationalization.md) - [Performance testing](contributing/performance-testing.md) +Reference guides provide tables and other information to look up while working +on Ghost: + +- [Node.js compatibility](reference/node-compatibility.md) + ### Finding Issues to Work On - [Good First Issues](https://github.com/TryGhost/Ghost/labels/good%20first%20issue) - Great for newcomers diff --git a/docs/contributing/development-setup.md b/docs/contributing/development-setup.md index b2c729b14a7..7b5929d5985 100644 --- a/docs/contributing/development-setup.md +++ b/docs/contributing/development-setup.md @@ -15,6 +15,9 @@ Install: - [Corepack](https://nodejs.org/api/corepack.html), included with supported Node.js distributions +For Node.js support in older Ghost releases, see the +[Node.js compatibility reference](../reference/node-compatibility.md). + The default environment binds ports `80`, `2368`, `3306`, `6379`, `8025`, and `8026`. Stop local services using those ports before starting Ghost. diff --git a/docs/reference/node-compatibility.md b/docs/reference/node-compatibility.md new file mode 100644 index 00000000000..80ca63b3dc8 --- /dev/null +++ b/docs/reference/node-compatibility.md @@ -0,0 +1,81 @@ +# Ghost, Node.js, and Ghost-CLI compatibility + +Ghost, Node.js, and Ghost-CLI have independent release cycles. This reference +records the points where their supported version ranges changed. + +Use the versions pinned in [`.nvmrc`](../../.nvmrc) and +[`package.json`](../../ghost/core/package.json) when working on the current +Ghost codebase. Use this history when maintaining or upgrading an older Ghost +installation. + +There are two different compatibility relationships: + +- Ghost's `engines.node` and `engines.cli` fields define the Node.js versions + that can run that Ghost release and the minimum Ghost-CLI version it accepts. +- Ghost-CLI's own `engines.node` field defines the Node.js versions that can run + that Ghost-CLI release. + +## Ghost compatibility + +Rows record compatibility changes and useful final-version milestones. A blank +Node.js or Ghost-CLI cell means that value did not change in that release. + +| Release date | Ghost release | Node.js support | Minimum Ghost-CLI | Change | +| --- | --- | --- | --- | --- | +| 2017-12-05 | >= 1.18.3 | `^4.5.0 \|\| ^6.9.0 \|\| ^8.9.0` | | | +| 2018-04-17 | >= 1.22.3 | | `^1.7.0` | Added Ghost-CLI compatibility requirement | +| 2018-05-04 | >= 1.22.5 | `^6.9.0 \|\| ^8.9.0` | | Removed Node.js 4 | +| 2018-07-24 | 1.25.0 | | | Last 1.x migrations | +| 2019-12-18 | 1.26.2 | | | Last 1.x version | +| 2018-08-16 | 2.0.0 | | `^1.9.0` | Initial 2.x support | +| 2018-10-30 | >= 2.4.0 | `^6.9.0 \|\| ^8.9.0 \|\| ^10.12.0` | | Added Node.js 10 | +| 2018-11-07 | >= 2.5.0 | `^6.9.0 \|\| ^8.9.0 \|\| ^10.13.0` | | Bumped Node.js 10 minimum | +| 2019-06-04 | >= 2.23.2 | `^8.9.0 \|\| ^10.13.0` | | Removed Node.js 6 | +| 2019-07-16 | >= 2.25.7 | `^8.10.0 \|\| ^10.13.0` | | Bumped Node.js 8 minimum | +| 2019-10-14 | 2.37.0 | | | Last 2.x migrations | +| 2021-01-29 | 2.38.3 | | | Last 2.x version | +| 2019-10-22 | 3.0.0 | `^8.16.0 \|\| ^10.13.0 \|\| ^12.10.0` | `^1.12.0` | Initial 3.x support; added Node.js 12 | +| 2020-03-02 | >= 3.9.0 | `^10.13.0 \|\| ^12.10.0` | | Removed Node.js 8 | +| 2020-11-03 | >= 3.37.0 | `^10.13.0 \|\| ^12.10.0 \|\| ^14.15.0` | | Added Node.js 14 | +| 2021-01-26 | 3.41.0 | | | Last 3.x migrations | +| 2022-01-22 | 3.42.9 | | | Last 3.x version | +| 2021-03-15 | 4.0.0 | | `^1.16.0` | Initial 4.x support | +| 2021-05-11 | >= 4.5.0 | `^12.22.1 \|\| ^14.16.1` | `^1.17.0` | Removed Node.js 10 | +| 2021-10-29 | >= 4.21.0 | `^12.22.1 \|\| ^14.17.0 \|\| ^16.13.0` | | Added Node.js 16 | +| 2022-04-22 | >= 4.45.0 | `^14.17.0 \|\| ^16.13.0` | | Removed Node.js 12 | +| 2022-05-23 | 5.0.0 | `^14.17.0 \|\| ^16.13.0` | `^1.17.0` | Initial 5.x support | +| 2022-12-02 | >= 5.25.0 | `^14.17.0 \|\| ^16.13.0 \|\| ^18.0.0` | | Added Node.js 18 | +| 2023-01-05 | >= 5.27.0 | `^14.18.0 \|\| ^16.13.0 \|\| ^18.12.1` | | Bumped Node.js 14 and 18 minimums | +| 2023-05-05 | >= 5.47.0 | `^16.13.0 \|\| ^18.12.1` | | Removed Node.js 14 | +| 2023-07-14 | >= 5.54.1 | `^16.14.0 \|\| ^18.12.1` | | Bumped Node.js 16 minimum | +| 2023-10-04 | >= 5.67.0 | | `^1.25.0` | Bumped Ghost-CLI minimum | +| 2023-10-27 | >= 5.71.0 | `^18.12.1` | | Removed Node.js 16 | +| 2024-04-19 | >= 5.82.3 | `^18.12.1 \|\| ^20.11.1` | `^1.26.0` | Added Node.js 20 and bumped Ghost-CLI minimum | +| 2025-02-21 | >= 5.110.0 | `^18.12.1 \|\| ^20.11.1 \|\| ^22.13.1` | `^1.27.0` | Added Node.js 22 and bumped Ghost-CLI minimum | +| 2025-08-04 | 6.0.0 | `^22.13.1` | `^1.27.0` | Initial 6.x support; removed Node.js 18 and 20 | +| 2026-04-13 | >= 6.29.0 | | `^1.29.1` | Bumped Ghost-CLI minimum | +| 2026-06-19 | >= 6.46.0 | `^22.18.0` | | Bumped Node.js 22 minimum | +| 2026-07-17 | >= 6.53.0 | `^22.23.1` | | Bumped Node.js 22 minimum | + +## Ghost-CLI Node.js compatibility + +This table describes the Node.js runtime required to execute Ghost-CLI. It is +separate from the minimum Ghost-CLI version accepted by Ghost above. + +| Release date | Ghost-CLI release | Node.js support | Change | +| --- | --- | --- | --- | +| 2017-07-22 | 1.0.0 | `^4.5.0 \|\| ^6.5.0` | Initial 1.x support | +| 2017-10-09 | 1.1.3 | `^4.5.0 \|\| ^6.9.0` | Bumped Node.js 6 minimum | +| 2017-10-30 | 1.2.0 | `^4.5.0 \|\| ^6.9.0 \|\| ^8.8.0` | Added Node.js 8 | +| 2017-11-10 | 1.2.1 | `^4.5.0 \|\| ^6.9.0 \|\| ^8.9.0` | Bumped Node.js 8 minimum | +| 2018-05-01 | 1.7.2 | `^6.9.0 \|\| ^8.9.0` | Removed Node.js 4 | +| 2018-10-30 | 1.9.7 | `^6.9.0 \|\| ^8.9.0 \|\| ^10.12.0` | Added Node.js 10 | +| 2018-11-07 | 1.9.8 | `^6.9.0 \|\| ^8.9.0 \|\| ^10.13.0` | Bumped Node.js 10 minimum | +| 2019-10-21 | 1.12.0 | `^8.16.0 \|\| ^10.13.0 \|\| ^12.10.0` | Added Node.js 12; removed Node.js 6; bumped Node.js 8 minimum | +| 2021-03-01 | 1.16.0 | `^10.13.0 \|\| ^12.10.0 \|\| ^14.15.0` | Added Node.js 14; removed Node.js 8 | +| 2021-10-28 | 1.18.0 | `^12.22.1 \|\| ^14.17.0 \|\| ^16.13.0` | Added Node.js 16; removed Node.js 10; bumped minimums | +| 2022-12-02 | 1.24.0 | `^12.22.1 \|\| ^14.17.0 \|\| ^16.13.0 \|\| ^18.0.0` | Added Node.js 18 | +| 2024-03-19 | 1.26.0 | `^12.22.1 \|\| ^14.17.0 \|\| ^16.13.0 \|\| ^18.0.0 \|\| ^20.11.1` | Added Node.js 20 | +| 2025-02-13 | 1.27.0 | `^12.22.1 \|\| ^14.17.0 \|\| ^16.13.0 \|\| ^18.0.0 \|\| ^20.11.1 \|\| ^22.11.0` | Added Node.js 22 | +| 2026-03-23 | 1.28.6 | `^20.11.1 \|\| ^22.11.0 \|\| ^24.0.0` | Added Node.js 24; removed Node.js 12, 14, 16, and 18 | +| 2026-07-09 | 1.30.0 | `^22.13.0 \|\| ^24.0.0` | Removed Node.js 20; bumped Node.js 22 minimum | From b45ecaaec43937a29a24fa64d052e945a203455e Mon Sep 17 00:00:00 2001 From: Hannah Wolfe Date: Sun, 16 Aug 2026 17:35:45 +0100 Subject: [PATCH 2/2] Added codebase documentation guidance (#29998) Adds high level documentation about our documentation. Gives an outline of the intended structure, the boundaries, who is expected to keep it up to date and what considerations to keep in mind when making changes. --- AGENTS.md | 1 + docs/README.md | 1 + docs/contributing/documentation.md | 98 ++++++++++++++++++++++++++++++ 3 files changed, 100 insertions(+) create mode 100644 docs/contributing/documentation.md diff --git a/AGENTS.md b/AGENTS.md index b91f2682d03..3c5d55fb57c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,6 +11,7 @@ Start with: - [Development setup](docs/contributing/development-setup.md) - [Contribution workflow](docs/contributing/workflow.md) +- [Writing codebase documentation](docs/contributing/documentation.md) - [Testing](docs/contributing/testing.md) - [Shipping](docs/contributing/shipping.md) - [Monorepo structure](docs/codebase/monorepo-structure.md) diff --git a/docs/README.md b/docs/README.md index 8ec0f0afaaa..053c6ccdf49 100644 --- a/docs/README.md +++ b/docs/README.md @@ -90,6 +90,7 @@ Practice and contributor guides explain how to make and verify changes: - [API design](practices/api-design.md) - [Database migrations](practices/database-migrations.md) - [Browser E2E testing](contributing/e2e-testing.md) +- [Codebase documentation](contributing/documentation.md) - [Email testing](contributing/testing-email.md) - [Error handling](practices/error-handling.md) - [Internationalization](practices/internationalization.md) diff --git a/docs/contributing/documentation.md b/docs/contributing/documentation.md new file mode 100644 index 00000000000..3d4cea20a42 --- /dev/null +++ b/docs/contributing/documentation.md @@ -0,0 +1,98 @@ +# Writing Codebase Documentation + +Ghost's codebase documentation explains how to understand, change, test, and +ship this repository. It is public and reviewed alongside the code it +describes. + +## Choose the Right Home + +Give each topic one canonical home. Link to that source instead of copying it +into another documentation surface. + +| Content | Home | +| --- | --- | +| Codebase-wide setup, workflow, architecture, and practices | `/docs` | +| Package, service, app, or test-suite details | A README beside the code | +| Canonical domain language | A `CONTEXT.md` beside the domain | +| Relationships between bounded contexts | The root `CONTEXT-MAP.md` | +| Contribution policy and the contributor entry point | `.github/CONTRIBUTING.md` | +| Agent-only execution rules and constraints | The nearest `AGENTS.md` or repository skill | +| Product, API, theme, and self-hosting documentation | [ghost.org/docs](https://ghost.org/docs/) | +| Proposals, company process, private operations, and temporary work | The internal Ghost workspace | + +- Keep the root README focused on introducing Ghost and directing contributors + to the codebase documentation. +- Use `/docs` for guidance that crosses workspace or domain boundaries. +- Keep package or service details beside the code and link to them from an + overview where useful. + +## Context Files + +- A `CONTEXT.md` is a glossary for a bounded context: its important terms, + precise meanings, and terms to avoid. +- Keep architecture and implementation details in the nearby README or an + appropriate codebase guide. +- Add each bounded context and its relationships to the root `CONTEXT-MAP.md`. + +## Who Should Update the Docs? + +Whoever changes or introduces a documented concept is responsible for updating +its documentation. + +- Update the docs in the same pull request as the code, workflow, command, or + behaviour they describe. +- Check the nearest README, `/docs`, and agent guidance when a change crosses + those surfaces. +- Update both the overview and focused guide when readers need both. +- Ask an owner of the affected area to review specialist guidance, but do not + leave the documentation work for them to discover later. + +## Write for the Current Codebase + +- Check guidance against the current code, scripts, tests, and configuration. +- Run or otherwise verify commands and paths where practical. +- Leave one canonical answer and link to it instead of copying it. +- Use direct language, short sections, and examples from real commands or code. +- Keep critical information in an overview, then link with “For more detail” to + a focused guide. +- Use relative repository links and link to stable files or symbols rather than + line numbers. +- Copy public-safe images into the repository instead of using expiring Notion + URLs. + +## Keep Public and Private Guidance Separate + +- Keep repository documentation public and useful to contributors. +- Never include credentials, secrets, customer or site data, private repository + details, internal hostnames, or incident and operational procedures. +- Document public integration boundaries where contributors need them; keep + private deployment and operations in the internal workspace. +- Review private source material before the first commit. Never commit it and + remove the sensitive parts later. + +## Keep Human and Agent Guidance in Sync + +- Treat human-readable documentation as the source of truth for facts and + conventions shared by people and agents. +- Keep `AGENTS.md` focused on directions to canonical docs and agent-specific + execution constraints. +- Link repository skills to the canonical guide instead of repeating it. +- Update human documentation and any agent entry points that need to discover + it in the same pull request. + +## Check Your Change + +Run the repository hygiene check before submitting documentation changes: + +```bash +pnpm check +pnpm lint:docs +git diff --check origin/main...HEAD +``` + +- Check links manually; `pnpm lint:docs` does not currently validate Markdown + links. +- Confirm another document does not give a different answer. +- Confirm no private or temporary material is being published. +- After a migrated guide is live, replace links to its Notion source and retire + the old page.