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

[slorber]

Pre-flight checklist

• I have read the Contributing Guidelines on pull requests.
• If this is a code change: I have written unit tests and/or added dogfooding pages to fully verify the new behavior.
• If this is a new API or substantial change: the PR has an accompanying issue (closes #0000) and the maintainers have approved on my working plan.

Motivation

Clarify how we handle versioning, breaking changes, semver, public API and all things important for releasing 2.0

Test Plan

preview

Test links

Deploy preview: https://deploy-preview-7706--docusaurus-2.netlify.app/community/release-process

Related issues/PRs

#6113

[netlify]

✅ [V2]

Name	Link
🔨 Latest commit	9d147ad
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/62d02df51e9a9c0008ab29ff
😎 Deploy Preview	https://deploy-preview-7706--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[github-actions]

⚡️ Lighthouse report for the deploy preview of this PR

URL	Performance	Accessibility	Best Practices	SEO	PWA	Report
/	🟢 96	🟢 100	🟢 100	🟢 100	🟢 90	Report
/docs/installation	🟠 85	🟢 100	🟢 100	🟢 100	🟢 90	Report

[github-actions]

Size Change: +3.57 kB (0%)

Total Size: 805 kB

Filename	Size	Change
website/.docusaurus/globalData.json	52.8 kB	+157 B (0%)
website/build/assets/css/styles.********.css	106 kB	-597 B (-1%)
website/build/assets/js/main.********.js	608 kB	+4.01 kB (+1%)

ℹ️ View Unchanged

Filename	Size
website/build/index.html	38.9 kB

_{compressed-size-action}

[Josh-Cena]

LGTM

One question is about TypeScript types. What accounts as "safe"? For example, does changing a type from non-generic to generic count as breaking? Two generic arguments to three? string to a literal union? Or only removal of types counts? Are all exported types stable? (e.g. we have a lot of types in @docusaurus/plugin-content-docs/lib/sidebars/types) Should we split @docusaurus/types into /internal as well?

[slorber]

One question is about TypeScript types.

I was pretty sure you'll comment on this TS line 😄 Definitively needs a bit more clarification.

What accounts as "safe"? For example, does changing a type from non-generic to generic count as breaking? Two generic arguments to three?

I guess it is safe if the new generic types has a retro-compatible default value.

string to a literal union?

It probably depends if the type is used as an input or output (ie input plugin option vs output attribute used as component className)

Or only removal of types counts?

Removal, rename...

Are all exported types stable? (e.g. we have a lot of types in @docusaurus/plugin-content-docs/lib/sidebars/types)

I think we should only guarantee the stability of the theme props types, and not necessarily mention the types exported by content plugins, which are currently quite messy.

I mean:

declare module '@theme/DocCard' {
  import type {PropSidebarItem} from '@docusaurus/plugin-content-docs';

  export interface Props {
    readonly item: PropSidebarItem;
  }

  export default function DocCard(props: Props): JSX.Element;
}

We can guarantee the <DocCard> component will keep exporting a Props type, and it will keep containing an item attribute with a retro-compatible shape. The user does not need to know about PropSidebarItem and the docs plugin, they could just use Props["item"].

Ideally, we shouldn't refactor all types with a Prop prefix convention, as those are injected into frontend routes and the entry point components are configurable.

Should we split @docusaurus/types into /internal as well?

What I see in practice is that almost all those types are already part of our public API.

There are a few exceptions like InitializedPlugin, and types related to modules/registry/chunks... We can probably move these directly in core instead?

It should make it clearer think about all those types after that refactor: #7710

---

It's a bit hard to define what TS retro-compatibility is.

Sometimes adding a new attribute to an existing type leads to a subtle breaking change.

I think we should see it as a best effort, and try to avoid annoying TS users and plugin authors.

If we feel a change is likely to piss off anyone, we just don't backport it and keep it for the next version?

[Josh-Cena]

If the "type stability" is more of a good will than a hard commitment, I'm good.