Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: release process, versioning, breaking changes, public API surface #7706

Merged
merged 51 commits into from
Jul 14, 2022
Merged
Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
51 commits
Select commit Hold shift + click to select a range
dad4a09
add initial release process doc
slorber Jun 30, 2022
afa763f
add public api surface section
slorber Jun 30, 2022
dd96856
editorial changes
Josh-Cena Jul 1, 2022
18c3870
Update website/community/5-release-process.md
Josh-Cena Jul 7, 2022
567eee6
Update website/community/5-release-process.md
Josh-Cena Jul 7, 2022
d22abf0
mention docs server/node api is for some third-party plugin authors
slorber Jul 1, 2022
079aab2
docs: add RedGradient to showcase (#7704)
redcamel Jul 1, 2022
8f0223d
docs: add RedGradient to showcase (#7704)
redcamel Jul 1, 2022
1587b73
docs: mention MDXContent (#7705)
Josh-Cena Jul 1, 2022
c641079
docs: add Novu to showcase (#7712)
scopsy Jul 1, 2022
b9198a6
feat(deploy): copy local git config to tmp repo (#7702)
ghostsquad Jul 1, 2022
a83fb26
feat(theme-translations): Swedish translation (#7715)
johnie Jul 3, 2022
b00cc1c
chore: upgrade dependencies (#7684)
Josh-Cena Jul 4, 2022
eae7123
docs: add GitHub pages deployment troubleshooting guide (#7723)
Josh-Cena Jul 4, 2022
05e56b3
chore(deps): bump github/codeql-action from 2.1.14 to 2.1.15 (#7724)
dependabot[bot] Jul 5, 2022
ba75655
chore: bump devcontainer to node 18 (#7726)
jqshuv Jul 6, 2022
4fae95d
refactor(theme-common): move useDocsPreferredVersion() to public api …
slorber Jul 6, 2022
b018feb
refactor(types): split into multiple files (#7710)
slorber Jul 6, 2022
f7c79c0
feat(algolia-search): allow translating search modal (#7666)
forresst Jul 6, 2022
7b1e1af
docs: add pincman site to showcase (#7718)
pincman Jul 6, 2022
dd67646
fix(theme): show blog post edit link even when no tag & not truncated…
anaclumos Jul 6, 2022
2f5a170
fix(theme-translations): improve grammar of zh translation (#7696)
AkagiYui Jul 7, 2022
65c8a39
fix(theme-translations): improve fr translation (#7731)
forresst Jul 7, 2022
d46e311
docs: add Mixcore CMS to showcase (#7730)
Smilefounder Jul 7, 2022
2c68ef5
docs: swizzle react-live with eject (#7739)
SheetJSDev Jul 8, 2022
c931ffb
feat(theme-translations): Dutch translation (#7732)
reinvanhaaren Jul 8, 2022
41449e1
refactor(theme): split BlogPostItem into smaller theme subcomponents …
slorber Jul 8, 2022
f76ffbc
refactor(theme): nest theme icons under subfolder @theme/Icon/* (#7740)
slorber Jul 8, 2022
522c34c
chore: prepare v2.0.0-beta.22 release (#7741)
slorber Jul 8, 2022
32c3b1b
chore: regenerate beta.22 examples (#7742)
slorber Jul 8, 2022
2ed9967
chore: upgrade dependencies (#7754)
Josh-Cena Jul 9, 2022
b892280
fix(theme-classic): fix Layout theme height CSS (#7752)
LichLord91 Jul 9, 2022
c09793b
docs: update evantay showcase image (#7757)
DigiPie Jul 11, 2022
b698e8f
docs: move Yeecord repo to organization (#7758)
kane50613 Jul 11, 2022
0a58d85
fix(algolia-search): test for canUseIntersectionObserver (#7761)
RoiArthurB Jul 11, 2022
08f6db8
docs: add StackQL Provider Registry to showcase (#7760)
jeffreyaven Jul 11, 2022
2729820
refactor(core): use has instead of get to test for existence in ExecE…
Josh-Cena Jul 11, 2022
ffad396
fix(theme-classic): validate options properly (#7755)
Josh-Cena Jul 11, 2022
91eabe3
chore(deps): bump actions/setup-node from 3.3.0 to 3.4.0 (#7764)
dependabot[bot] Jul 12, 2022
512bd45
chore(theme-translations): complete ko translations (#7762)
anaclumos Jul 12, 2022
5740ca9
fix(migrate): import siteConfig with file extension (#7766)
Josh-Cena Jul 12, 2022
2a8d0d0
fix(deploy): revert "feat(deploy): copy local git config to tmp repo …
ghostsquad Jul 12, 2022
31ff663
docs: add EverShop website to showcase (#7765)
treoden Jul 13, 2022
08283d8
chore: bump Infima to 0.2.0-alpha.42, fix a:hover link bug (#7771)
slorber Jul 13, 2022
ce29062
fix(sitemap): complete gracefully when all pages have noIndex meta (#…
Josh-Cena Jul 14, 2022
66fbc3c
fix(core): swizzle --eject js should not copy theme .d.ts files (#7776)
slorber Jul 14, 2022
f639242
refactor(theme): fix duplicate page metadata usage (#7777)
slorber Jul 14, 2022
b34d7bf
Minor core public api list update
slorber Jul 14, 2022
9b4f299
rc => no breaking changes + cut the version branch
slorber Jul 14, 2022
8af52b0
consistent list format
slorber Jul 14, 2022
9d147ad
merge
slorber Jul 14, 2022
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion website/community/4-canary.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ import {

Docusaurus has a canary releases system.

It permits you to **test new unreleased features** as soon as the pull requests are merged.
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.

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

Expand Down
197 changes: 197 additions & 0 deletions website/community/5-release-process.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,197 @@
# Release process

Let's see how Docusaurus handles **versioning, releases and breaking changes**.

:::info

This topic is particularly important for highly customized sites that may have difficulties to upgrade.

:::

## Semantic versioning {#semantic-versioning}

Docusaurus versioning is based on the `major.minor.patch` scheme and respects [Semantic Versioning](https://semver.org/).

Respecting Semantic Versioning is important for multiple reasons:

- It **guarantees simple minor version upgrades**, as long as you only use the [public API](##public-api-surface)
- It follows front-end ecosystem conventions
- A new major version is an opportunity to thoroughly document breaking changes
- A new major/minor version is an opportunity to communicate new features through a blog post

:::note

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.

[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.

:::

### Major versions {#major-versions}

The `major` version number is incremented on **every breaking change**.

Whenever a new major version is released, we publish:

- a blog post with feature highlights, major bug fixes, **breaking changes, and upgrade instructions**.
- an exhaustive changelog entry

:::tip

Read our [public API surface](##public-api-surface) section to clearly understand what we consider as a breaking change.

:::

### Minor versions {#minor-versions}

The `minor` version number is incremented on every significant retro-compatible change.

Whenever a new minor version is released, we publish:

- a blog post with a list of feature highlights and major bug fixes
- an exhaustive changelog entry

:::tip

If you only use our [public API surface](##public-api-surface), you should be able to upgrade in no time!

:::

### Patch versions {#patch-versions}

The `patch` version number is incremented on bugfixes releases.

Whenever a new patch version is released, we only publish an exhaustive changelog entry.
slorber marked this conversation as resolved.
Show resolved Hide resolved

## Versions {#versions}

```mdx-code-block
import {
StableMajorVersion,
NextMajorVersion,
StableMajorBranchLink,
NextMajorBranchLink,
} from "@site/src/components/Versions";
```

The Docusaurus team is usually working on 2 major versions at the same time:

- **Docusaurus <StableMajorVersion/>**: the **stable**, on the <StableMajorBranchLink/> branch
- **Docusaurus <NextMajorVersion/>**: the **next** version, on the <NextMajorBranchLink/> branch

### Stable version {#stable-version}

The stable version (v<StableMajorVersion/>, on <StableMajorBranchLink/>) is recommended for most Docusaurus users.

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.

:::info

After a new stable version has been released, the former stable version will continue to receive support for **major security issues** for **3 months**, but all features will be frozen, as well as non-critical bugs.
Josh-Cena marked this conversation as resolved.
Show resolved Hide resolved

It is recommended to upgrade within that time frame to the new stable version.

:::

### Next version {#next-version}

The next version (v<NextMajorVersion/>, on <NextMajorBranchLink/>) is the version the Docusaurus team is currently working on.

The <NextMajorBranchLink/> branch is the **default target branch** for all pull requests, including core team and external contributions.

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.

There are 3 ways to use the next version:

- with an `alpha`, `beta` or `rc` pre-release
- with the `@next` npm dist tag for the latest pre-release
- with a [canary release](./4-canary.md) for the very latest features

:::tip

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.

:::

:::caution

Breaking changes can happen on the next version: detailed upgrade instructions are available in the changelog and pull requests.

At the `beta` and `rc` (release candidate) phases, we avoid introducing major breaking changes.

:::

## Public API surface {#public-api-surface}

Docusaurus commits to respect Semantic Versioning. This means that whenever changes occur in Docusaurus public APIs and break backward compatibility, we will increment the `major` version number.
Josh-Cena marked this conversation as resolved.
Show resolved Hide resolved

:::tip

Docusaurus guarantees public API retro-compatibility across `minor` versions. Unless you use internal APIs, `minor` version upgrades should be easy.

:::

We will outline what accounts as the public API surface.

### Core public API {#core-public-api}

✅ Our public API includes:

- Docusaurus config
- Docusaurus client APIs
- Docusaurus CLI
- Preset options
- Plugin options
- Plugin lifecycle APIs
- Theme config
- TypeScript types
- We still retain the freedom to make types stricter (which may break type-checking).

:::tip

For non-theme APIs, any documented API is considered public (and will be stable); any undocumented API is considered internal.

:::

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.

### Theming public API {#theming-public-api}

Docusaurus has a very flexible theming system:

- You can use custom CSS
- You can [swizzle](/docs/swizzling) any React theme component

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.

✅ Our public theming API includes:

- [Theme class names](/docs/styling-layout#theme-class-names)
- [Infima](/docs/styling-layout#styling-your-site-with-infima) class names and CSS variables
- React components that are [safe to swizzle](/docs/swizzling#what-is-safe-to-swizzle)
- The theme user experience
- Browser support

:::tip

You may not be able to achieve your site customization through this public API.

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.

:::

❌ Our public theming API **excludes**:

- The DOM structure
- CSS module class names with a hash suffix (usually targeted with `[class*='myClassName']` selectors)
- React components that are [unsafe or forbidden to swizzle](/docs/swizzling#what-is-safe-to-swizzle)
- React components that import from `@docusaurus/theme-common/internal`
- The exact visual appearance of the theme

:::note

When [swizzling](/docs/swizzling) safe components, you might encounter components that import undocumented APIs from `@docusaurus/theme-common` (without the `/internal` subpath).

We still maintain retro-compatibility on those APIs (hence they are marked as "safe"), but we don't encourage a direct usage.

:::
37 changes: 37 additions & 0 deletions website/src/components/Versions.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,43 @@ export function StableVersion(): JSX.Element {
return <span>{currentVersion}</span>;
}

// TODO temporary: assumes main is already on v3 (not the case yet)
function useNextMajorVersionNumber(): number {
return 3; // TODO later read from main@package.json or something...
}
function useStableMajorVersionNumber(): number {
// -1 because website is published from main, which is the next version
return useNextMajorVersionNumber() - 1;
}

export function NextMajorVersion(): JSX.Element {
const majorVersionNumber = useNextMajorVersionNumber();
return <span>{majorVersionNumber}</span>;
}

export function StableMajorVersion(): JSX.Element {
const majorVersionNumber = useStableMajorVersionNumber();
return <span>{majorVersionNumber}</span>;
}

function GitBranchLink({branch}: {branch: string}): JSX.Element {
return (
<a href={`https://github.com/facebook/docusaurus/tree/${branch}`}>
<code>{branch}</code>
</a>
);
}

export function StableMajorBranchLink(): JSX.Element {
const majorVersionNumber = useStableMajorVersionNumber();
const branch = `docusaurus-v${majorVersionNumber}`;
slorber marked this conversation as resolved.
Show resolved Hide resolved
return <GitBranchLink branch={branch} />;
}

export function NextMajorBranchLink(): JSX.Element {
return <GitBranchLink branch="main" />;
}

export function InsertIfCanaryVersionUnknown({
children,
}: {
Expand Down