From 2d0a07be8483811d804983b073abb0d636842e84 Mon Sep 17 00:00:00 2001 From: GeoffCoxMSFT Date: Wed, 14 Feb 2024 09:40:46 -0800 Subject: [PATCH 1/4] Drafted RFC --- .../convergence/long-term-support-plan.md | 122 ++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 rfcs/react-components/convergence/long-term-support-plan.md diff --git a/rfcs/react-components/convergence/long-term-support-plan.md b/rfcs/react-components/convergence/long-term-support-plan.md new file mode 100644 index 0000000000000..4584257c63659 --- /dev/null +++ b/rfcs/react-components/convergence/long-term-support-plan.md @@ -0,0 +1,122 @@ +# RFC: Long-term support (LTS) plan + +Geoff Cox +Tudor Papa +Gouttierre Gomes + +2023-02-06 + +## Summary + +We need to establish a long-term support (LTS) plan to set expectations with partners and the open-source community. This includes building a plan for the sunset and retirement of older versions of Fluent. + +For example, this issue [Fluent v8 LTS/EOL (long-term support / end of life)?](https://github.com/microsoft/fluentui/discussions/29100) brought up the question. + +## Background + +We currently support v7, v8, and v9 versions of Fluent UI React and v0 of Northstar/Stardust. + +- v0 is active in the master branch. It is still supported by Teams, but all new feature work happens in v9. +- v7 is in sunset. Only critical issues are fixed. The last fix was over 6 months ago (2023-08-17). +- v8 is active in the master branch. Important issues raised by partners are fixed and partners actively develop on v8. + = v9 is active in the master branch. It is Fluent's focus for feature development. + +## Problem statement + +We need to: + +1. Communicate LTS plans for each version to partners and the open-source community. +2. Plan for sunset/retirement of old versions. +3. Coordinate with partners that contribute to or own packages in our repository. + +## Proposal: Manage versions with branches + +These are somewhat sequential, but work can be done as soon as it makes sense. + +#### Get v9 to parity with v8 + +To make v9 the official current branch, developers need to be able to do everything they could with v8. + +Our status as of 2014-02: + +- In preview: Rating, SearchBox, TeachingPopover, Motion +- In compat: Calendar, DatePicker, TimePicker +- In progress Nav, SwatchPicker, PeoplePicker, Carousel, +- Not started: Calendar, ColorPickerCompat, +- On hold: Coachmark +- Unknown: Chart, Keytips, MarqueeSelection, ActivityItem + +Our planning cadence is scheduling component work to get to parity. + +Components specific to one product should be moved into the partner repository. Components with limited shared re-use should be moved into the community contrib repository. Lower-value components or eccentric features should be considered for deprecation. + +We should set a date when we expect to be at parity and communicate it to partners. + +#### Publish an LTS policy with each version + +We should add a Long Term Support section to the README.MD of each version. It should detail what stage the version is in, what kind of issues will be fixed by our team, what kind of issues should be fixed by the community, and the expected response time to issue triage and PR review. + +We should add pointers from the wiki FAQ back to the README.MD for each version. + +#### Retire v7 + +We should announce an end-of-life to v7. Proposed: June 30th, 2024. We would lock the branch from any changes, disable and archive any build pipelines, and replace public documentation sites with a redirect to a notice that v7 is retired. + +Any partners wanting to continue using v7, should take a snapshot of the code and integrate it into their own repositories and build it. + +#### Separate v0, v8 and v9 branches + +v7 is already in its own branch. v0, v8, and v9 are in the master branch which causes some confusion for developers. + +1. Create a v8 branch from master +2. Create a northstar-v0 branch from master +3. Remove all v9 code from the northstar-v0, and v8 branches +4. Remove all v0 and v8 code from the master branch +5. Update v8 components to take npm dependencies on compat components +6. Update any migration components to take npm dependencies on v8 components +7. Update v0, v8 builds to publish only v0, v8 components +8. Update v9 build to publish only v9 components +9. Update README.MD in each branch to cover its version and point to the other branches +10. Update ADO pipelines to handle each different branch (triggers, builds, releases) +11. Update ADO documentation for releasing each version + +- Keep cross-version compat components in master (v9). +- Keep migration components in master (v9). + +This plan requires communicating to partners that own their own v0 and v8 based packages in the master branch that they will need to start working on them in the new branches. + +There should be a cut-over date where branches are locked for changes and then the steps taken (scripts?) to make the change followed by the branches being unlocked. It would be good to time +the cutover to a time of low activity for all teams globally. + +#### Flatten master branch + +With northstar-v0 and v8 no longer in the master branch, we can reduce the depth of the tree by bringing components within the react-components folder up one level. + +#### Sunset v8 + +After retiring v7, announce v8 is in sunset mode. Only critical bugs will be fixed. We will no longer be moving React forward in v8. Set a retirement date for one year out. + +#### Define team tenets for active versions + +The Fluent team size doesn't allow for supporting more than 2 versions of Fluent. We should consider policy where we don't start active development on a new major version until the oldest version is retired (or at least in sunset). We can have a next branch and do lots of experimentation there, but there would be no support for this branch. + +Branch renames make it possible to have an easier current verson change if we do next version development it its own branch. We can rename master to vX and then rename next to master. + +Note: We should also consider renaming master to main. + +### Pros and Cons + +- 👍 v7 is already isolated in own branch, requiring no changes and will be familiar to partners +- 👍 branches provide independent policy allowing for easier management +- 👍 folder depth is reduced and packages more discoverable +- 👍 build times should be moderately faster with no if/then logic +- 👍 builds should be more reliable as changes are always specific to that version + +- 👎 more branches means more enlisting, github configuration, and pipeline configuration +- 👎 aging builds for sunset and retiring versions means keeping track of different build approaches +- 👎 we'll be asking partners to absorb more pain while we're also asking the to migrate + +## Open Issues + +- Need detailed review by Martin as the v-build lead and build expert +- This is asking for a lot of effort by the v-build team. Should find ways to have the entire team help out, although there are some sequential work items that will make it difficult. From b2b7518d6b9c40776ba2870d48e4322a1cc8b004 Mon Sep 17 00:00:00 2001 From: "Geoff Cox (Microsoft)" Date: Mon, 26 Feb 2024 09:36:10 -0800 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Martin Hochel Co-authored-by: Makoto Morimoto --- .../convergence/long-term-support-plan.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/rfcs/react-components/convergence/long-term-support-plan.md b/rfcs/react-components/convergence/long-term-support-plan.md index 4584257c63659..7d2fd40fc6a40 100644 --- a/rfcs/react-components/convergence/long-term-support-plan.md +++ b/rfcs/react-components/convergence/long-term-support-plan.md @@ -1,10 +1,8 @@ # RFC: Long-term support (LTS) plan -Geoff Cox -Tudor Papa -Gouttierre Gomes +Geoff Cox, Tudor Papa, Gouttierre Gomes -2023-02-06 +2024-02-06 ## Summary @@ -19,7 +17,7 @@ We currently support v7, v8, and v9 versions of Fluent UI React and v0 of Norths - v0 is active in the master branch. It is still supported by Teams, but all new feature work happens in v9. - v7 is in sunset. Only critical issues are fixed. The last fix was over 6 months ago (2023-08-17). - v8 is active in the master branch. Important issues raised by partners are fixed and partners actively develop on v8. - = v9 is active in the master branch. It is Fluent's focus for feature development. +- v9 is active in the master branch. It is Fluent's focus for feature development. ## Problem statement @@ -37,7 +35,7 @@ These are somewhat sequential, but work can be done as soon as it makes sense. To make v9 the official current branch, developers need to be able to do everything they could with v8. -Our status as of 2014-02: +Our status as of 2024-02: - In preview: Rating, SearchBox, TeachingPopover, Motion - In compat: Calendar, DatePicker, TimePicker @@ -60,7 +58,7 @@ We should add pointers from the wiki FAQ back to the README.MD for each version. #### Retire v7 -We should announce an end-of-life to v7. Proposed: June 30th, 2024. We would lock the branch from any changes, disable and archive any build pipelines, and replace public documentation sites with a redirect to a notice that v7 is retired. +We should announce an end-of-life to v7. Proposed: June 30th, 2024. We would [lock the branch from any changes](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#lock-branch), disable and archive any build pipelines, and replace public documentation sites with a redirect to a notice that v7 is retired. Any partners wanting to continue using v7, should take a snapshot of the code and integrate it into their own repositories and build it. @@ -114,7 +112,7 @@ Note: We should also consider renaming master to main. - 👎 more branches means more enlisting, github configuration, and pipeline configuration - 👎 aging builds for sunset and retiring versions means keeping track of different build approaches -- 👎 we'll be asking partners to absorb more pain while we're also asking the to migrate +- 👎 we'll be asking partners who regularly contribute to the repo to absorb more pain while we're also asking them to migrate ## Open Issues From 9aeb940a0b59fd21c017afaac21c241e5b05b972 Mon Sep 17 00:00:00 2001 From: GeoffCoxMSFT Date: Mon, 26 Feb 2024 14:27:06 -0800 Subject: [PATCH 3/4] Updates --- .../convergence/long-term-support-plan.md | 51 ++++++++++++------- 1 file changed, 32 insertions(+), 19 deletions(-) diff --git a/rfcs/react-components/convergence/long-term-support-plan.md b/rfcs/react-components/convergence/long-term-support-plan.md index 7d2fd40fc6a40..58cdebc2cd8a5 100644 --- a/rfcs/react-components/convergence/long-term-support-plan.md +++ b/rfcs/react-components/convergence/long-term-support-plan.md @@ -35,16 +35,8 @@ These are somewhat sequential, but work can be done as soon as it makes sense. To make v9 the official current branch, developers need to be able to do everything they could with v8. -Our status as of 2024-02: - -- In preview: Rating, SearchBox, TeachingPopover, Motion -- In compat: Calendar, DatePicker, TimePicker -- In progress Nav, SwatchPicker, PeoplePicker, Carousel, -- Not started: Calendar, ColorPickerCompat, -- On hold: Coachmark -- Unknown: Chart, Keytips, MarqueeSelection, ActivityItem - -Our planning cadence is scheduling component work to get to parity. +The [Fluent UI React component roadmap](https://github.com/orgs/microsoft/projects/786] shows +the plan for each component providing parity. Components specific to one product should be moved into the partner repository. Components with limited shared re-use should be moved into the community contrib repository. Lower-value components or eccentric features should be considered for deprecation. @@ -56,6 +48,12 @@ We should add a Long Term Support section to the README.MD of each version. It s We should add pointers from the wiki FAQ back to the README.MD for each version. +We should consider documentation similar to Node JS [previous releases](https://nodejs.org/en/about/previous-releases). + +- ACTIVE = active development in main (always LTS) +- MAINTENANCE = only critical bug fixes +- EOL = frozen code, no changes possible + #### Retire v7 We should announce an end-of-life to v7. Proposed: June 30th, 2024. We would [lock the branch from any changes](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#lock-branch), disable and archive any build pipelines, and replace public documentation sites with a redirect to a notice that v7 is retired. @@ -64,16 +62,16 @@ Any partners wanting to continue using v7, should take a snapshot of the code an #### Separate v0, v8 and v9 branches -v7 is already in its own branch. v0, v8, and v9 are in the master branch which causes some confusion for developers. +v7 is already in its own branch. v0, v8, and v9 are in the master branch which causes some confusion for developers1. -1. Create a v8 branch from master -2. Create a northstar-v0 branch from master +1. Create a v8 branch from master2 +2. Create a northstar-v0 branch from master2 3. Remove all v9 code from the northstar-v0, and v8 branches 4. Remove all v0 and v8 code from the master branch -5. Update v8 components to take npm dependencies on compat components -6. Update any migration components to take npm dependencies on v8 components -7. Update v0, v8 builds to publish only v0, v8 components -8. Update v9 build to publish only v9 components +5. Update v8 components to take npm dependencies on compat components3. +6. Update migration component4 to take npm dependencies on v8 components +7. Update v0, v8 builds to publish only v0, v8 components5 +8. Update v9 build to publish only v9 components5 9. Update README.MD in each branch to cover its version and point to the other branches 10. Update ADO pipelines to handle each different branch (triggers, builds, releases) 11. Update ADO documentation for releasing each version @@ -86,6 +84,16 @@ This plan requires communicating to partners that own their own v0 and v8 based There should be a cut-over date where branches are locked for changes and then the steps taken (scripts?) to make the change followed by the branches being unlocked. It would be good to time the cutover to a time of low activity for all teams globally. +1 Multiple migration partners have asked 'where is the v9 code?', 'are packages at the same level as react or react-components v8 or v9?', and 'do improvements in react or react-components get cherry-picked to the other folder?'. We've had similar questions come up on our shield and 1JS channels. + +2 Includes branch protection policies. + +3 react-portal-compat, react-portal-compat-context + +4 react-migration-v0-v9, react-migration-v8-v9 + +5 Today our builds have some conditional code specific to v8 or v9 builds. This work would remove those conditions. + #### Flatten master branch With northstar-v0 and v8 no longer in the master branch, we can reduce the depth of the tree by bringing components within the react-components folder up one level. @@ -100,20 +108,25 @@ The Fluent team size doesn't allow for supporting more than 2 versions of Fluent Branch renames make it possible to have an easier current verson change if we do next version development it its own branch. We can rename master to vX and then rename next to master. -Note: We should also consider renaming master to main. +#### Consider renaming master to main + +In 2020, as part of replacing exclusionary terms with more inclusive ones, many repositories started renaming the master branch to main. New repositories in GitHub now default to main. We should take this opportunity to do the same if we are renaming branches. ### Pros and Cons - 👍 v7 is already isolated in own branch, requiring no changes and will be familiar to partners - 👍 branches provide independent policy allowing for easier management - 👍 folder depth is reduced and packages more discoverable -- 👍 build times should be moderately faster with no if/then logic +- 👍 build times should be moderately faster with no if/then logic1 - 👍 builds should be more reliable as changes are always specific to that version +- 👍 build technology can evolve more rapidly as there is less compatibility work to consider and reduces build script surface area. - 👎 more branches means more enlisting, github configuration, and pipeline configuration - 👎 aging builds for sunset and retiring versions means keeping track of different build approaches - 👎 we'll be asking partners who regularly contribute to the repo to absorb more pain while we're also asking them to migrate +1 As well, some components with large test snapshots such as react-charting won't slow test run times during builds. + ## Open Issues - Need detailed review by Martin as the v-build lead and build expert From 50ea7711ae6ebb2fbb5da896c5c740db1bcae670 Mon Sep 17 00:00:00 2001 From: GeoffCoxMSFT Date: Wed, 28 Feb 2024 09:04:07 -0800 Subject: [PATCH 4/4] Updates --- .../convergence/long-term-support-plan.md | 80 ++++++++++++++----- 1 file changed, 62 insertions(+), 18 deletions(-) diff --git a/rfcs/react-components/convergence/long-term-support-plan.md b/rfcs/react-components/convergence/long-term-support-plan.md index 58cdebc2cd8a5..5776d75342477 100644 --- a/rfcs/react-components/convergence/long-term-support-plan.md +++ b/rfcs/react-components/convergence/long-term-support-plan.md @@ -1,6 +1,6 @@ # RFC: Long-term support (LTS) plan -Geoff Cox, Tudor Papa, Gouttierre Gomes +Geoff Cox, Tudor Papa, Gouttierre Gomes, Martin Hochell 2024-02-06 @@ -15,24 +15,44 @@ For example, this issue [Fluent v8 LTS/EOL (long-term support / end of life)?](h We currently support v7, v8, and v9 versions of Fluent UI React and v0 of Northstar/Stardust. - v0 is active in the master branch. It is still supported by Teams, but all new feature work happens in v9. -- v7 is in sunset. Only critical issues are fixed. The last fix was over 6 months ago (2023-08-17). +- v7 is in maintenance. Only critical issues are fixed. The last fix was over 6 months ago (2023-08-17). - v8 is active in the master branch. Important issues raised by partners are fixed and partners actively develop on v8. -- v9 is active in the master branch. It is Fluent's focus for feature development. +- v9 is active in the master branch. It is our focus for feature development. + +We also have multiple projects in our master branch: + +- Fluent UI Core (react & react-components) +- Fluent UI web components +- partner Fluent extensions (react-charting) +- partner Fluent themes (azure-themes) + +These projects have different versions and different release cadences. ## Problem statement We need to: 1. Communicate LTS plans for each version to partners and the open-source community. -2. Plan for sunset/retirement of old versions. +2. Plan for sunset/retirement of old versions and plan an approach for future versions. 3. Coordinate with partners that contribute to or own packages in our repository. +4. Be careful to sequence changes to avoid unnecessary churn for consumers or overloading the v-build team. -## Proposal: Manage versions with branches +## Proposal: Manage version lifetime with branches These are somewhat sequential, but work can be done as soon as it makes sense. +#### Retire v7 + +Proposed ETA: End of FY2024. + +We should announce an end-of-life to v7. We would [lock the branch from any changes](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#lock-branch), disable and archive any build pipelines, and replace public documentation sites with a redirect to a notice that v7 is retired. + +Any partners wanting to continue using v7, should take a snapshot of the code and integrate it into their own repositories and build it. + #### Get v9 to parity with v8 +Proposed ETA: End of FY2024. + To make v9 the official current branch, developers need to be able to do everything they could with v8. The [Fluent UI React component roadmap](https://github.com/orgs/microsoft/projects/786] shows @@ -44,6 +64,8 @@ We should set a date when we expect to be at parity and communicate it to partne #### Publish an LTS policy with each version +Proposed ETA: Following commit of this RFC + We should add a Long Term Support section to the README.MD of each version. It should detail what stage the version is in, what kind of issues will be fixed by our team, what kind of issues should be fixed by the community, and the expected response time to issue triage and PR review. We should add pointers from the wiki FAQ back to the README.MD for each version. @@ -54,24 +76,28 @@ We should consider documentation similar to Node JS [previous releases](https:// - MAINTENANCE = only critical bug fixes - EOL = frozen code, no changes possible -#### Retire v7 +#### Get build to latest tooling and robust CI pipelines -We should announce an end-of-life to v7. Proposed: June 30th, 2024. We would [lock the branch from any changes](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#lock-branch), disable and archive any build pipelines, and replace public documentation sites with a redirect to a notice that v7 is retired. - -Any partners wanting to continue using v7, should take a snapshot of the code and integrate it into their own repositories and build it. +There is some work in progress to move to the latest verson of Nx and to [make the release pipeline more reliable](https://github.com/microsoft/fluentui/issues/27758). We want to have a build system that we know works before creating new branches; akin to having unit tests before refactoring code. #### Separate v0, v8 and v9 branches +Proposed ETA: H1 or early H2 FY2025 + v7 is already in its own branch. v0, v8, and v9 are in the master branch which causes some confusion for developers1. -1. Create a v8 branch from master2 +> We need to be able to distinguish between the multiple projects and their multiple versions when creating branches, so the names are more than just the version number. + +> v-build is confident that we can create scripts to do the branching and most of the update work. This would allow us to cut branches quickly and have only a weekend day of unavailability. + +1. Create a react-v8 branch from master2 2. Create a northstar-v0 branch from master2 -3. Remove all v9 code from the northstar-v0, and v8 branches +3. Remove all v9 code from the northstar-v0, and react-v8 branches 4. Remove all v0 and v8 code from the master branch 5. Update v8 components to take npm dependencies on compat components3. 6. Update migration component4 to take npm dependencies on v8 components -7. Update v0, v8 builds to publish only v0, v8 components5 -8. Update v9 build to publish only v9 components5 +7. Update northstar-v0, react-v8 builds to publish only their components5 +8. Update master build to not publish v0 or v8 components5 9. Update README.MD in each branch to cover its version and point to the other branches 10. Update ADO pipelines to handle each different branch (triggers, builds, releases) 11. Update ADO documentation for releasing each version @@ -79,7 +105,7 @@ v7 is already in its own branch. v0, v8, and v9 are in the master branch which c - Keep cross-version compat components in master (v9). - Keep migration components in master (v9). -This plan requires communicating to partners that own their own v0 and v8 based packages in the master branch that they will need to start working on them in the new branches. +This plan requires communicating to partners that own their own v0 and v8 based packages in the master branch that they will need to start working on them in the new branches. It also requires careful communication to consumers about any open PRs just before cut-over might be lost. There should be a cut-over date where branches are locked for changes and then the steps taken (scripts?) to make the change followed by the branches being unlocked. It would be good to time the cutover to a time of low activity for all teams globally. @@ -94,13 +120,21 @@ the cutover to a time of low activity for all teams globally. 5 Today our builds have some conditional code specific to v8 or v9 builds. This work would remove those conditions. -#### Flatten master branch +#### Organize master branch (a little more) + +With northstar-v0 and react-v8 no longer in the master branch, top-level folders should be project named (react-components, web-components, and shared infrastructure). Within those folders will be the standard apps, packages, scripts, etc. + +We can remove the extra react-components folder inside of packages as we'll have a top-level folder. -With northstar-v0 and v8 no longer in the master branch, we can reduce the depth of the tree by bringing components within the react-components folder up one level. +#### react-v8, northstar-v0 to maintenance and eventually EOL -#### Sunset v8 +Proposed ETAs: -After retiring v7, announce v8 is in sunset mode. Only critical bugs will be fixed. We will no longer be moving React forward in v8. Set a retirement date for one year out. +- End of FY2024: Message partners intent to put v8 into maintenance +- Start of H3 FY2025: react-v8 and northstar-v0 maintenance mode +- End of FY2025: react-v8, northstar-v0 EOL + +After retiring v7, announce v8 is in maintenance mode. Only critical bugs will be fixed. We will no longer be moving React forward in v8. Set a retirement date for one year out. #### Define team tenets for active versions @@ -112,6 +146,16 @@ Branch renames make it possible to have an easier current verson change if we do In 2020, as part of replacing exclusionary terms with more inclusive ones, many repositories started renaming the master branch to main. New repositories in GitHub now default to main. We should take this opportunity to do the same if we are renaming branches. +#### Consider renaming v7 to react-v7 + +At some point after v7's EOL, we can rename for consistency. + +#### Approach for future versions + +The future version approach doesn't have to be too specific at this point. We want to ensure that we have the option of doing work in vNext branches when we don't want to expose that work in main. We also want to be able to take an evolutionary approach of adding the next version components to main, keeping current version components compatible, and then converting current version components to shims around next version components. + +We'll have another RFC or vNext plan for more details. + ### Pros and Cons - 👍 v7 is already isolated in own branch, requiring no changes and will be familiar to partners