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

Conversation

slorber
Copy link
Collaborator

@slorber slorber commented Jun 30, 2022

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

@slorber slorber added the pr: documentation This PR works on the website or other text documents in the repo. label Jun 30, 2022
@slorber slorber requested review from lex111 and Josh-Cena as code owners June 30, 2022 18:04
@facebook-github-bot facebook-github-bot added the CLA Signed Signed Facebook CLA label Jun 30, 2022
@netlify
Copy link

netlify bot commented Jun 30, 2022

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

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
Copy link

github-actions bot commented Jun 30, 2022

⚡️ 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
Copy link

github-actions bot commented Jun 30, 2022

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

Copy link
Collaborator

@Josh-Cena Josh-Cena left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

@Josh-Cena Josh-Cena changed the title docs: release process, versioning, breaking changes, public api surface docs: release process, versioning, breaking changes, public API surface Jul 1, 2022
@slorber
Copy link
Collaborator Author

slorber commented Jul 1, 2022

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
Copy link
Collaborator

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

website/community/5-release-process.md Outdated Show resolved Hide resolved
website/community/5-release-process.md Outdated Show resolved Hide resolved
website/community/5-release-process.md Outdated Show resolved Hide resolved
website/src/components/Versions.tsx Show resolved Hide resolved
Josh-Cena and others added 15 commits July 7, 2022 09:18
Co-authored-by: Joshua Chen <[email protected]>
Co-authored-by: Sébastien Lorber <[email protected]>
Co-authored-by: Joshua Chen <[email protected]>
Co-authored-by: Sébastien Lorber <[email protected]>
* chore: upgrade dependencies

* fix

* reupgrade

* downgrade
Bumps [github/codeql-action](https://github.com/github/codeql-action) from 2.1.14 to 2.1.15.
- [Release notes](https://github.com/github/codeql-action/releases)
- [Changelog](https://github.com/github/codeql-action/blob/main/CHANGELOG.md)
- [Commits](github/codeql-action@41a4ada...3f62b75)

---
updated-dependencies:
- dependency-name: github/codeql-action
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <[email protected]>

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
* fix: bump devcontainer to node 16

* fix: bump devcontainer directly to nodejs 18
This was referenced May 13, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
CLA Signed Signed Facebook CLA pr: documentation This PR works on the website or other text documents in the repo.
Projects
None yet
Development

Successfully merging this pull request may close these issues.