From c1b9a00dcaf58f7b44762c0fe2208406c09934dc Mon Sep 17 00:00:00 2001 From: Mason Tejera <17346018+mltejera@users.noreply.github.com> Date: Tue, 21 May 2024 14:11:23 -0700 Subject: [PATCH] Martins comments. Add release cycle. --- .../component-implementation-guide.md | 17 +- docs/react-v9/contributing/release-cycle.md | 167 ++++++++++++++++++ 2 files changed, 170 insertions(+), 14 deletions(-) create mode 100644 docs/react-v9/contributing/release-cycle.md diff --git a/docs/react-v9/contributing/component-implementation-guide.md b/docs/react-v9/contributing/component-implementation-guide.md index 540e5615fd7370..4ea642be38f73c 100644 --- a/docs/react-v9/contributing/component-implementation-guide.md +++ b/docs/react-v9/contributing/component-implementation-guide.md @@ -32,7 +32,7 @@ These components are more than just a convergence of the implementations of the # Versioning Overview -Each component is released in multiple phases. This process has changed as of July 2023, and is outlined in more detail in the [[new release process v9 packages]] article. In summary: +Each component is released in multiple phases. This process has changed as of July 2023, and is outlined in more detail in the [v9 package release cycle](release-process.md). In summary: 1. **Kickoff phase**: Package has `-preview` suffix and is not yet published to NPM (private). 2. **Preview phase**: Package has `-preview` suffix and is published with version `0.(major).(minor|patch)`. Breaking changes will be marked as minor, but announced as such in changelogs. @@ -166,7 +166,6 @@ Once the first draft of the spec has been reviewed, you can get started on the i - Respect Figma tokens (and use the Provider) - Respect API principles, shorthands and slots handling - No dependency on v0/v7/v8 -- Add tsdoc `/** */` comments to all public APIs in your component You can follow examples of other converged components for the structure of the implementation, such as: @@ -224,8 +223,6 @@ Once the component has been released as unstable, you should perform additional - When deciding what tests to write, generally the tests should cover all states in your component's styling hook (`use{Component}Styles`). - **Bundle Size Tests** - Example: [Button.fixture.js](https://github.com/microsoft/fluentui/blob/master/packages/react-components/react-button/bundle-size/Button.fixture.js) -- **Performance Tests** - - Example: [Button.tsx](https://github.com/microsoft/fluentui/blob/master/apps/perf-test-react-components/src/scenarios/Button.tsx) - **Manual Accessibility Tests** - For more info see [Manual Accessibility Review Checklist](https://github.com/microsoft/fluentui/wiki/Manual-Accessibility-Review-Checklist) @@ -247,18 +244,10 @@ Organize a bug bash with other Fluent UI crews. This is the last chance to verif Once all validation has been completed, the component is ready for a stable release! 🎉 -Use the following script to move the package to stable, replacing `MYCOMPONENT` with the appropriate package name: +Use the following script to move the package to stable, replacing `your-component` with the appropriate package name: ```bash -yarn nx generate prepare-initial-release --project @fluentui/react-MYCOMPONENT-preview --phase=stable +yarn nx generate prepare-initial-release --project @fluentui/react-your-component-preview --phase=stable ``` -- Rename the package to remove `-preview` (should be done by the script). -- Deprecate the existing `-preview` package in NPM. -- Change beachball's `disallowedChangeTypes` to `"major", "prerelease"` in its package.json - - Example: [react-button/package.json](https://github.com/microsoft/fluentui/blob/master/packages/react-components/react-button/package.json) -- Add exports to [`@fluentui/react-components`](https://github.com/microsoft/fluentui/blob/master/packages/react-components/react-components/src/index.ts) -- Update `README.md` and `{Component}Description.md` to remove references to the component being unstable. -- Update `stories/{Component}/index.stories.tsx` to move the stories from `"Preview Components/"` to `"Components/"`. - **Important**: Once the component has been released as stable, it can no longer have any breaking changes before the next major release of the library. diff --git a/docs/react-v9/contributing/release-cycle.md b/docs/react-v9/contributing/release-cycle.md new file mode 100644 index 00000000000000..62c385319b640e --- /dev/null +++ b/docs/react-v9/contributing/release-cycle.md @@ -0,0 +1,167 @@ + + +- [New process/life-cycle flow](#new-processlife-cycle-flow) + - [Major differences with previous unstable/stable flow](#major-differences-with-previous-unstablestable-flow) + - [FAQ](#faq) + - [Is there still a need for `_unstable` suffixes for hooks/utilities?](#is-there-still-a-need-for-_unstable-suffixes-for-hooksutilities) + - [What's the process for updating already existing unstable package](#whats-the-process-for-updating-already-existing-unstable-package) + - [package not released to npm yet (`9.0.0-alpha.x`):](#package-not-released-to-npm-yet-900-alphax) + - [package already released to npm as `9.0.0-(alpha|beta|rc).x`:](#package-already-released-to-npm-as-900-alphabetarcx) +- [Dev Guide](#dev-guide) + - [1. Kick-off phase](#1-kick-off-phase) + - [2. Preview phase](#2-preview-phase) + - [3. Stable phase](#3-stable-phase) + + + +# New process/life-cycle flow + + +unstable-stable-api-new-flow + + +## Major differences with previous unstable/stable flow + +- unstable/preview components don't start with `9.0.0-.0` +- unstable/preview components will never be part of `@fluentui/react-components` suite. They can be used by installing independent package. +- 👉 **`react-components/unstable` is frozen and deprecated - this api cannot be changed in any way** +- both stable and unstable(preview) should always use `^` within package.json dependencies (no more pinned versions for pre-releases needed) +- `*-preview` packages are part of our official storybook public docs right after 1st release + - one can provide public doc-site link right away to designers/partners to test it out **without any hacks** +- unstable/preview packages follow strict semantic versioning via `0.major.(minor|patch)` pattern + - if your changes within preview package are breaking use change-type `minor` + - if you add new features or fixes within preview package use change-type `patch` + +## FAQ + +### Is there still a need for `_unstable` suffixes for hooks/utilities? + +Any utilities that are in a stable package **cannot be broken**. Therefore, the purpose of the `_unstable` suffix has changed. If the owner feels confident that the API of that hook/utility has a sufficient level of extensibility, there is no need for a suffix. However, if there are doubts about the implementation that can be addressed in the future the `_unstable` suffix can communicate that to users. A stable version (i.e. one without the suffix) can be reserved for future use once there is more confidence the use case or functionality. + +Any hooks/utilities with the `_unstable` suffix **cannot be removed and cannot be broken until the next major version**. + +### What's the process for updating already existing unstable package + +#### package not released to npm yet (`9.0.0-alpha.x`): + +> All packages migration PR https://github.com/microsoft/fluentui/pull/28474 + +
+Let's say you have already created `packages/react-components/react-control` package which is in unstable phase. + +Follow these steps: + +1. rename package directory and api.md + +```sh +mv packages/react-components/react-control packages/react-components/react-control-preview +mv packages/react-components/react-control/etc/react-control.api.md packages/react-components/react-control/etc/react-control-preview.api.md +``` + +2. Update `README.md` + +```diff +-# @fluentui/react-control-preview ++# @fluentui/react-control +``` + +3. Update `package.json` + +```diff +{ +- "name": "@fluentui/react-control", ++ "name": "@fluentui/react-control-preview", +- "version": "9.0.0-alpha.0", ++ "version": "0.0.0", + "beachball": { + "disallowedChangeTypes": [ + "major", +- "minor", +- "patch", ++ "prerelease" + ] +}, +} +``` + +4. Update `project.json` + +```diff +{ +- "name": "@fluentui/react-control", ++ "name": "@fluentui/react-control-preview", +} +``` + +5. Update `jest.config.js` + +```diff +module.exports = { +- displayName: 'react-control', ++ displayName: 'react-control-preview', +} +``` + +6. Update `tsconfig.base.json` and `tsconfig.base.all.json` + +```diff +"paths": { +- "@fluentui/react-control": ["packages/react-components/react-control/src/index.ts"] ++ "@fluentui/react-control-preview": ["packages/react-components/react-control-preview/src/index.ts"] +} +``` + +7. Update `/github/CODEOWNERS` + +```diff +-packages/react-components/react-control @microsoft/ ++packages/react-components/react-control-preview @microsoft/ +``` + +8. now when ready to release follow [Unstable phase (first release)](#unstable-phase-first-release) + +
+ +#### package already released to npm as `9.0.0-(alpha|beta|rc).x`: + +> automation PR in progress https://github.com/microsoft/fluentui/pull/28481 + +# Dev Guide + +Following chapters describe required steps for each phase. All of them are generated so it's only a matter of invoking proper generator. + +> Following graph sums those steps as well https://github.com/microsoft/fluentui/blob/master/tools/workspace-plugin/src/generators/prepare-initial-release/README.md#v9-release-process-flow + +## 1. Kick-off phase + +> automation status: implemented ✅ / https://github.com/microsoft/fluentui/pull/28474 + +Bootstrap new package, via `yarn create-package` + +```sh +yarn create-package + +# triggers standard prompt + +? Package name (do NOT include @fluentui prefix): react-hello +``` + +This will do the usual scaffolding and adds `-preview` suffix to the package name automatically + +## 2. Preview phase + +> automation status: implemented ✅ / https://github.com/microsoft/fluentui/pull/28505 + +```sh +yarn nx g @fluentui/workspace-plugin:prepare-initial-release --project @fluentui/react-one-preview --phase=preview +``` + +## 3. Stable phase + +> automation status: implemented ✅ / https://github.com/microsoft/fluentui/pull/28505 + +```sh +yarn nx g @fluentui/workspace-plugin:prepare-initial-release --project @fluentui/react-one-preview --phase=stable +``` + +- TODO: deprecate all released `*-preview` package version on npm on CI during release