# v8 release logistics

This document covers detailed plans (and brainstorming) related to package structure, versioning, beta publishing, and release publishing. It also contains the specific tasks to implement those plans.

Main doc: [Scope for V8 fluentui/react](/@fluentui/H17htZRlP)

[toc]

## What happens to our suite packages?

There is no OUFR v8: code currently in react-next and OUFR merges into react.

## What happens to child packages?

- Child packages are **no longer major-lockstep** (they use semver)
- This helps resolve the duplicate dependencies issue for partners
- If a sub-package is used by (especially re-exported from) the suite, it may **not** major bump except when the suite does
- This gets rid of the worst hotfix cases
- Breaking changes/experiments within major will be done in /next (then in major release, it will move to default and the old version can be /compat if needed)
- Each major release, we'll look at which /next things (or other desired breaking changes) are ready to be promoted
- In hotfix branches (`7.0` etc), find a way to ban non-hotfix publishing for child packages (beachball disallowedChangeTypes)
- We **go ahead with @uifabric to @fluentui renames**.
- Main advantage: clarity for users. Especially since we've decided to get rid of OUFR in v8, this is a great time to also (mostly) get rid of @uifabric. That way we're **(almost) ALL @fluentui and no more confusion!**
- To prevent partners from picking up duplicate dependencies, we'll **make alias @uifabric packages for `@fluentui/react` dependencies** which re-export the @fluentui versions.
- This will work to de-duplicate as long as consumers can upgrade `@uifabric/whatever` to the latest version
- Rather than generating with a script at publish time (which would be hugely complicated), the alias packages will be checked in to a sub-directory `<root>/alias-packages` (or `<root>/packages/aliases` or similar) so that they automatically pick up version bumps
- The alias packages will depend on and re-export the @fluentui version
- Probably also need to duplicate all the root files to avoid what will be perceived as an API break in a minor
- Packages which are not dependencies of `@fluentui/react` will be renamed outright (no alias). This includes experiments and charting.

### Which packages get aliases [in progress]

View and update list at https://github.com/microsoft/fluentui/issues/13384

## Branching and beta publishing

**Problem:** We can't publish a beta until OUFR and react-next are merged into react. But we can't merge them in the same branch as active 7.x development. Longer-term, we'll also need a hotfix branch for 7.x.

**Proposal:** 1-2 weeks before beta target date, move 7.x development into new `7.0` branch, which will later become the hotfix branch. Then move things around in master and publish the beta from there. (This is the opposite of the approach we took for v7 beta.)

**Details:** (see Tasks below for even more details)

- v0+v8-only PRs continue into master
- v7 development and publishing moves into a 7.0 branch
- Until release, any PR which should be in v7 goes to 7.0 first
- After official v8 release, all PRs should go to master first and cherry-pick to 7.0 as needed.
- Authors (especially core team) may do their own cherry-picks to master if preferred
- Release coordinator will periodically merge 7.0 changes into master
- Allow up to 1 week to prepare master for beta publishing
- Nothing (except possibly v0) is published out of master during this week
- This is when combining OUFR and react-next into react happens

## Tasks

### Before beta prep period

- [ ] Timing: check with Prague so the worst of the branch changes don't collide with when they need to release v0
- [ ] Address circular dependency issue in examples - see https://github.com/microsoft/fluentui/issues/14681
<!-- will probably not do this
- [ ] Website build (before or after beta)
- [ ] Look into making same release pipeline tasks work across 5/6/7/master (task group with variable?)
- [ ] Look into driving version switcher from manifest or something (to avoid needing manual updates across multiple files and branches)
-->

### 1-2 weeks before beta date

The tasks in this section need to be done in the specified order, in as rapid succession as possible to reduce disruption of development and time spent on merge conflicts.

- [ ] Stage 7.0 branch (work continues in master)
- [ ] Create the branch
- [ ] Set up branch policies
- [ ] Set up bot rules
- [ ] Set up release/publish build (npm tag `latest`)
- [ ] Set up website release
- [ ] Cherry-pick any new changes from master
- [ ] Active 7.x development moves to 7.0 branch
- [ ] Re-target any active PRs intended for 7.x
- [ ] Update release/publish builds:
- [ ] Disable release builds from master (temporary)
- [ ] Disable website releases from master (temporary)
- [ ] Enable release builds from 7.0
- [ ] Prepare master branch for beta development
- No publishing from master during this time (possible exception for v0)
- [ ] First in a separate branch:
- There may be multiple PRs to this branch, and it will need to periodically be updated from master
- [ ] OUFR/react-next merge
- [ ] Merge OUFR into react
- [ ] Merge react-next into react (last chance to review FC changes)
- [ ] Delete OUFR
- [ ] Make react-next be a pure re-export package from react (and bump version to 9-alpha)
- [ ] Automation or procedure to ensure they don't come back in a bad merge!
- [ ] Update code references to OUFR or react-next (enough to build)
- [ ] In master (after main move/delete is merged)
- [ ] date-time updates
- [ ] Move date-time components into suite as default
- [ ] Move old versions to /compat
- [ ] Make date-time package re-export components from suite
- [ ] @uifabric to @fluentui renames (and delete unneeded packages)
- [ ] Add @uifabric alias packages for suite dependencies
- [ ] Update versions of packages which will major-bump: `8.0.0-beta.1` or similar
- [ ] Cherry-pick any changes from 7.0
- [ ] Set up beta releases
- [ ] Update beachball settings to publish to `beta` npm tag where appropriate, and automatically increment prerelease versions
- [ ] Re-enable release/publish builds from master
- [ ] Ensure website does not update yet (unless we want to add special handling for 7 default/8 beta)
- Beta will be announced at this point (see [Communication section of main doc](https://hackmd.io/3IjQJtqHRl2mx_4nT0oDvQ?both#Communication))

### After beta is published

- [ ] Text cleanup pass to remove Fabric/office-ui-fabric-react/@uifabric/etc
- [ ] Files in repo
- [ ] wiki
- [ ] aka.ms/fabridemo
- [ ] other?
- [ ] Add 8 beta to aka.ms/fabricdemo?

### Just before release

- [ ] Prepare master branch for release (may require short code freeze)
- [ ] Last check for 7.0 changes to cherry-pick
- [ ] Pause publishing
- [ ] Update version numbers/publishing config to remove prerelease
- [ ] Sync version numbers of non-major-bumped packages to those in 7.0 branch
- [ ] In 7.0 branch, disable publishing of any packages which didn't major bump
- Should we entirely delete the packages (and pull the latest versions from npm instead) to make this more obvious?
- [ ] Switch aka.ms/fabricdemo to show 8 by default
- [ ] [Website](https://github.com/microsoft/fluentui/issues/14691)
- [ ] Update version switching everywhere to include 8 (and use by default) -- unless we've updated to a manifest-based solution
- [ ] version switcher in React homepage (in 5, 6, 7, master)
- [ ] index.html (master, don't know about 5/6/7)
- [ ] homepage.htm
- [ ] others?
- [ ] Enable website release of 8 from master
- [ ] Publish!
- [ ] Remove beta-specific contributing docs

# Future plans

## Reorganizing packages

At some point in the future, we want to re-organize our repo's package structure so it's easier for contributors to find things (and there are fewer things lumped into one folder).

Option 1:

packages/
  /alias-packages/    
  /web-components/
  /react/
    /suites/
      /react/
      /react-northstar
    /components/
      /react-button/
      /react-utilities/    
  /shared/
    /dom-utilities/

Option 2:

packages/
  /alias-packages/    
  /web-components/
  /suites/
    /web-components/
    /react/
    /react-northstar/
  /components/
    /react/
      /react-button/
    /web-components/
      /wc-button/
  /utilities/
    /react-utilities/
    /color-utilities/
    /dom-utilities/
    /random-utilities/
    /helpful-utilities/
    /harmful-utilities/

# Discussion: previous thoughts or still in progress

`^5.79.1-0` will match either `5.79.1` or `5.79.1-hotfixN` but will always pick up the latest version

https://semver.npmjs.com/

<!--
## What happens with our suite packages?
- Circular dependencies between separate packages [TODO: investigation]
- Package setup
- There is no OUFR v8
- Merge OUFR and react-next into react
- what happens to react-next?
- Question: Do we bump mergeStyles, utilities, etc to v8?
- Answer[David]: No, they stay v7 and it's ok we can still hotfix them
- **Question:** Is this violating customer expectations that the previous major version be stable (and not pick up new changes except hotfixes)?
- Next Steps:
- What is the 1,2,3 steps to do the above
- Where do examples live to avoid circular dependencies?
-->

## What's the hotfix story for child packages?

If we get rid of major-lockstep, hotfixing child packages gets messy.

**Scenario:**
- Someone needs to hotfix OUFR 7, but the actual issue is in utilities
- The version of utilities in the v7 branch is `7.1.2`, so OUFR 7 depends on `utilities@^7.1.2`
- Meanwhile, subsequent versions of utilities have been released out of master: `7.1.3`, `7.2.0`, etc
- Variant: utilities has bumped to 8.x in master
<!-- - Oddities of "prerelease" semver to keep in mind (all `-suffix` semver is considered prerelease):
- **Prerelease versions will NEVER satisfy a semver range**
- This means **guaranteed duplicates** if someone has 2 versions of
- `7.1.2-hotfix.1` is **less than** `7.1.2` -->

**Possibilities:**
- (1) Require fix to be checked in as usual in master (or in a child package hotfix branch if absolutely necessary)
- This means we should probably update tooling to *ban child package bumps* in v7 branch (since it could result in duplicates)
- If utilties is still on 7.x in master, require that the fix be checked in there (if it's not already there), and to get the fix the consumer must take the latest utilities version
- Downsides: they may not want to pick up all of the changes due to regression risk; may require package manager magic to get new version
- If utilities has advanced to 8.x in master, this gets messy... Possibilities:
- Make a special branch like `7.0-utilities` for the child package right before it major bumps
- With branch rules, CI builds, and release builds set up
- What happens if different child packages bump major versions at different points, and one needs hotfix from another? (semver might handle this if we're sticking with non-prerelease versions)
- ??? (forgot where this was going...)
- Use hotfix (technically prerelease) versions
- Don't think we have automated publishing for this (could be fixable)
- **Prerelease versions NEVER satisfy a semver range**, meaning we must either:
- Publish new versions of all v7-series packages with a specific dep on the hotfix version
- Which guarantees duplicates if the consumer has multiple OUFR versions, defeating the original point of this mess
- The consumer must use their package manager's pinning/resolution options to pin utilities to the new hotfix version (again awkward if the consumer has multiple OUFR versions)
- Subsequent fixes and fixes spanning multiple packages get very messy

**Even worse future scenario:**
- Someone needs a fix in button version 8
- button is now on version 9 or even 10 in master
- The suite package is still at version 8 and must continue depending on button 8 until the next major suite version (to avoid breaking changes to a re-exported API)
-

More questions:
- If hotfixes must be done in master, ... (I think this was about cherry-pick responsibility?)
- This is probably the reason why most major monorepos bump major versions of all monorepo packages in lock step...
- Major-lockstep: jest, babel, ...
- NOT major-lockstep: ...
- [react](https://github.com/facebook/react) seems to have multiple groups of packages which move in major-lockstep, plus experimental packages at a mix of versions (not sure if they ever need hotfixes)
- Avoids issue by not using a monorepo: webpack, ant-design, ...