Skip to content

Commit f913af0

Browse files
slorberzpaoJosh-Cena
authoredJul 14, 2022
docs: release process, versioning, breaking changes, public API surface (#7706)
Co-authored-by: Paul O’Shannessy <paul@oshannessy.com> Co-authored-by: Joshua Chen <sidachen2003@gmail.com> Co-authored-by: Sébastien Lorber <slorber@users.noreply.github.com>
·
v3.7.0v2.0.0-rc.1
1 parent 9788944 commit f913af0

File tree

4 files changed

+248
-1
lines changed

4 files changed

+248
-1
lines changed
 

‎packages/docusaurus-plugin-content-docs/src/server-export.ts

+4
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,10 @@
66
*/
77

88
// APIs available to Node.js
9+
// Those are undocumented but used by some third-party plugins
10+
// For this reason it's preferable to avoid doing breaking changes
11+
// See also https://github.com/facebook/docusaurus/pull/6477
12+
913
export {
1014
CURRENT_VERSION_NAME,
1115
VERSIONED_DOCS_DIR,

‎website/community/4-canary.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ import {
1616

1717
Docusaurus has a canary releases system.
1818

19-
It permits you to **test new unreleased features** as soon as the pull requests are merged.
19+
It permits you to **test new unreleased features** as soon as the pull requests are merged on the [next version](./5-release-process.md#next-version) of Docusaurus.
2020

2121
It is a good way to **give feedback to maintainers**, ensuring the newly implemented feature works as intended.
2222

‎website/community/5-release-process.md

+206
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
# Release process
2+
3+
Let's see how Docusaurus handles **versioning, releases and breaking changes**.
4+
5+
:::info
6+
7+
This topic is particularly important for highly customized sites that may have difficulties to upgrade.
8+
9+
:::
10+
11+
## Semantic versioning {#semantic-versioning}
12+
13+
Docusaurus versioning is based on the `major.minor.patch` scheme and respects [Semantic Versioning](https://semver.org/).
14+
15+
Respecting Semantic Versioning is important for multiple reasons:
16+
17+
- It **guarantees simple minor version upgrades**, as long as you only use the [public API](##public-api-surface)
18+
- It follows front-end ecosystem conventions
19+
- A new major version is an opportunity to thoroughly document breaking changes
20+
- A new major/minor version is an opportunity to communicate new features through a blog post
21+
22+
:::note
23+
24+
Releasing Docusaurus 2.0 took a very long time. From now on, Docusaurus will **release new major versions more regularly**. In practice, you can expect a new major version every 2–4 months.
25+
26+
[Major version numbers are not sacred](https://tom.preston-werner.com/2022/05/23/major-version-numbers-are-not-sacred.html), but we still group breaking changes together and avoid releasing major versions too often.
27+
28+
:::
29+
30+
### Major versions {#major-versions}
31+
32+
The `major` version number is incremented on **every breaking change**.
33+
34+
Whenever a new major version is released, we publish:
35+
36+
- a blog post with feature highlights, major bug fixes, **breaking changes, and upgrade instructions**.
37+
- an exhaustive changelog entry
38+
39+
:::tip
40+
41+
Read our [public API surface](##public-api-surface) section to clearly understand what we consider as a breaking change.
42+
43+
:::
44+
45+
### Minor versions {#minor-versions}
46+
47+
The `minor` version number is incremented on every significant retro-compatible change.
48+
49+
Whenever a new minor version is released, we publish:
50+
51+
- a blog post with a list of feature highlights and major bug fixes
52+
- an exhaustive changelog entry
53+
54+
:::tip
55+
56+
If you only use our [public API surface](##public-api-surface), you should be able to upgrade in no time!
57+
58+
:::
59+
60+
### Patch versions {#patch-versions}
61+
62+
The `patch` version number is incremented on bugfixes releases.
63+
64+
Whenever a new patch version is released, we publish:
65+
66+
- an exhaustive changelog entry
67+
68+
## Versions {#versions}
69+
70+
```mdx-code-block
71+
import {
72+
StableMajorVersion,
73+
NextMajorVersion,
74+
StableMajorBranchLink,
75+
NextMajorBranchLink,
76+
} from "@site/src/components/Versions";
77+
```
78+
79+
The Docusaurus team is usually working on 2 major versions at the same time:
80+
81+
- **Docusaurus <StableMajorVersion/>**: the **stable** version, on the <StableMajorBranchLink/> branch
82+
- **Docusaurus <NextMajorVersion/>**: the **next** version, on the <NextMajorBranchLink/> branch
83+
84+
:::note
85+
86+
The <StableMajorBranchLink/> branch is created just before releasing the first v<StableMajorVersion/> release candidate.
87+
88+
:::
89+
90+
### Stable version {#stable-version}
91+
92+
The stable version (v<StableMajorVersion/>, on <StableMajorBranchLink/>) is recommended for most Docusaurus users.
93+
94+
We regularly backport retro-compatible features, bug and security fixes from <NextMajorBranchLink/> to <StableMajorBranchLink/> with `git cherry-pick` to make them available to those not ready for the next version.
95+
96+
:::info
97+
98+
After a new stable version has been released, the former stable version will continue to receive support only for **major security issues** for **3 months**. Otherwise, all features will be frozen and non-critical bugs will not be fixed.
99+
100+
It is recommended to upgrade within that time frame to the new stable version.
101+
102+
:::
103+
104+
### Next version {#next-version}
105+
106+
The next version (v<NextMajorVersion/>, on <NextMajorBranchLink/>) is the version the Docusaurus team is currently working on.
107+
108+
The <NextMajorBranchLink/> branch is the **default target branch** for all pull requests, including core team and external contributions.
109+
110+
This version is recommended for **early adopters** that want to use the latest Docusaurus features as soon as possible. It is also a good way to help us by reporting bugs and giving some feedback.
111+
112+
There are 3 ways to use the next version:
113+
114+
- with an `alpha`, `beta` or `rc` pre-release
115+
- with the `@next` npm dist tag for the latest pre-release
116+
- with a [canary release](./4-canary.md) for the very latest features
117+
118+
:::tip
119+
120+
The next version passes all our automated tests and is used by the Docusaurus site itself. It is relatively safe: don't be afraid to give it a try.
121+
122+
:::
123+
124+
:::caution
125+
126+
Breaking changes can happen on the next version: detailed upgrade instructions are available in the changelog and pull requests.
127+
128+
At the `beta` and `rc` (release candidate) phases, we avoid introducing major breaking changes.
129+
130+
:::
131+
132+
## Public API surface {#public-api-surface}
133+
134+
Docusaurus commits to respecting Semantic Versioning. This means that whenever changes occur in Docusaurus public APIs and break backward compatibility, we will increment the `major` version number.
135+
136+
:::tip
137+
138+
Docusaurus guarantees public API retro-compatibility across `minor` versions. Unless you use internal APIs, `minor` version upgrades should be easy.
139+
140+
:::
141+
142+
We will outline what accounts as the public API surface.
143+
144+
### Core public API {#core-public-api}
145+
146+
✅ Our public API includes:
147+
148+
- Docusaurus config
149+
- Docusaurus client APIs
150+
- Docusaurus CLI
151+
- Preset options
152+
- Plugin options
153+
- Plugin lifecycle APIs
154+
- Theme config
155+
- Core plugins route component props
156+
- `@docusaurus/types` TypeScript types
157+
- We still retain the freedom to make types stricter (which may break type-checking).
158+
159+
:::tip
160+
161+
For non-theme APIs, any documented API is considered public (and will be stable); any undocumented API is considered internal.
162+
163+
:::
164+
165+
An API being "stable" means if you increment the patch or minor version of your Docusaurus installation without any other change, running `docusaurus start` or `docusaurus build` should not throw an error.
166+
167+
### Theming public API {#theming-public-api}
168+
169+
Docusaurus has a very flexible theming system:
170+
171+
- You can use custom CSS
172+
- You can [swizzle](/docs/swizzling) any React theme component
173+
174+
This system also implicitly creates a very large API surface. To be able to move fast and improve Docusaurus, we can't guarantee retro-compatibility.
175+
176+
✅ Our public theming API includes:
177+
178+
- [Theme class names](/docs/styling-layout#theme-class-names)
179+
- [Infima](/docs/styling-layout#styling-your-site-with-infima) class names and CSS variables
180+
- React components that are [safe to swizzle](/docs/swizzling#what-is-safe-to-swizzle)
181+
- The theme user experience
182+
- Browser support
183+
184+
:::tip
185+
186+
You may not be able to achieve your site customization through this public API.
187+
188+
In this case, please [report your customization use case](https://github.com/facebook/docusaurus/discussions/5468) and we will figure out how to expand our public API.
189+
190+
:::
191+
192+
❌ Our public theming API **excludes**:
193+
194+
- The DOM structure
195+
- CSS module class names with a hash suffix (usually targeted with `[class*='myClassName']` selectors)
196+
- React components that are [unsafe or forbidden to swizzle](/docs/swizzling#what-is-safe-to-swizzle)
197+
- React components that import from `@docusaurus/theme-common/internal`
198+
- The exact visual appearance of the theme
199+
200+
:::note
201+
202+
When [swizzling](/docs/swizzling) safe components, you might encounter components that import undocumented APIs from `@docusaurus/theme-common` (without the `/internal` subpath).
203+
204+
We still maintain retro-compatibility on those APIs (hence they are marked as "safe"), but we don't encourage a direct usage.
205+
206+
:::

‎website/src/components/Versions.tsx

+37
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,43 @@ export function StableVersion(): JSX.Element {
9292
return <span>{currentVersion}</span>;
9393
}
9494

95+
// TODO temporary: assumes main is already on v3 (not the case yet)
96+
function useNextMajorVersionNumber(): number {
97+
return 3; // TODO later read from main@package.json or something...
98+
}
99+
function useStableMajorVersionNumber(): number {
100+
// -1 because website is published from main, which is the next version
101+
return useNextMajorVersionNumber() - 1;
102+
}
103+
104+
export function NextMajorVersion(): JSX.Element {
105+
const majorVersionNumber = useNextMajorVersionNumber();
106+
return <span>{majorVersionNumber}</span>;
107+
}
108+
109+
export function StableMajorVersion(): JSX.Element {
110+
const majorVersionNumber = useStableMajorVersionNumber();
111+
return <span>{majorVersionNumber}</span>;
112+
}
113+
114+
function GitBranchLink({branch}: {branch: string}): JSX.Element {
115+
return (
116+
<a href={`https://github.com/facebook/docusaurus/tree/${branch}`}>
117+
<code>{branch}</code>
118+
</a>
119+
);
120+
}
121+
122+
export function StableMajorBranchLink(): JSX.Element {
123+
const majorVersionNumber = useStableMajorVersionNumber();
124+
const branch = `docusaurus-v${majorVersionNumber}`;
125+
return <GitBranchLink branch={branch} />;
126+
}
127+
128+
export function NextMajorBranchLink(): JSX.Element {
129+
return <GitBranchLink branch="main" />;
130+
}
131+
95132
export function InsertIfCanaryVersionUnknown({
96133
children,
97134
}: {

0 commit comments

Comments
 (0)
Please sign in to comment.