---
tags: build
---

# Converged package versioning

Follow-up of [Challenges of major version bumps in a monorepo](/DwJ-KIyXRlyR-uV1xB_UDA)

## Proposal

### Now

- Create new suite package `react-components` which will be published next week to Nova (3-4 components)
- It will re-export existing converged components packages
- Caveat: we will not publicize individual packages for now (except for react-button). Readme: don't use this, use react-components.

Version number for react-components and individual converged packages: **see open questions**

### Soon

(Next couple weeks but not blocking version 8 release or first Nova preview)

- Add readiness and convergence status badges to readmes as discussed elsewhere
- Move converged components into a separate folder
- Add tooling to enforce that converged may not depend on v8 stuff

### Later

- Suite+seperate packages will lockstep version on Major releases

## Reasoning

- Leaves us open to future decisions in either direction (indvidual packages or suite)
- Will revisit once we learn more from integrating this with customers
- Why major lockstep?
- Implementation complexity of all other options
- Not optimizing our versioning for other teams' upgrade problems

## Requirements

- Mix and Match of existing and converged is important, need to use FUR / FURN + converged at the same time
- The suite must major-bump if any package it re-exports major-bumps. This is a reality of semver.
- You can't use two versions of the same name side by side, hence the proposal of a new suite `@fluentui/react-components`.

### Non-requirements

We are **NOT** optimizing our versioning approach for these things:
- Other teams' upgrade problems. We probably need to help with this, but in a different way. (David/Ken/etc work on module federation and other solutions)
- Historically there's been a fear that if we don't improve handling of multiple suite versions on the same page (and the upgrade experience in general), [some product team] will revolt and fork the library.
- In theory, if we're providing value, even if people do fork, they'll come back.
- But we also need to be customer-focused: listen to partners' pain points and help them out
- Hotfixes to a specific previous version (`@fluentui/whatever@x.y.z-hotfix.1`): These are very rarely needed, so it's okay to handle them manually (even if it's painful) if/when the need arises.

## Open questions

### Converged package versions

Proposal:
- All converged packages (individual and `react-components`) start at `9.0.0-alpha.0`
- in theory we would prefer `0.x` (per semver spec this means "not yet ready"), but this poses communication issues due to extensive misuse of `0.x` in JS community -- so probably better to use explicit prerelease suffixes
- design is convinced we're making "v9" so...just go with it?
- When ready to preview with partners, go to `-beta.0`
- When ready to release, what's the major version?

TBD:
- What dist-tag should we use at what points?
- `alpha` when `-alpha`, `beta` when `-beta`
- [check](https://docs.npmjs.com/cli/v7/commands/npm-dist-tag) on handling of `latest` (for a new package that's only ever been prerelease with `alpha` dist-tag, does `latest` get automatically created? what does it point to?)
- any cleanup of dist-tag for existing packages?

### Branching for future major versions of legacy suite

If we need to release a new major version of `@fluentui/react` at some point (which we probably don't plan to, but it could potentially become necessary for various reasons)...how is the sustaining branch for v8 handled, since there are already converged packages publishing as 9.x?
- Create a new `8.0` branch
- Delete everything except the v8-only packages from that branch
- If v8 packages have started using anything converged, they must pull it from npm

### Full list of converged packages

Converged packages must not reference v8 packages. We also need to know which packages are following which versioning strategy.

(Need TOOLING to enforce ASAP)

#### Ready for beta

Utilities:
- make-styles
- uses v8: set-version
- react-make-styles
- react-provider
- uses v8: react-hooks, set-version
- react-shared-contexts *(used by v8)*
- react-theme
- react-theme-provider
- react-utilities

Components:
- react-avatar
- react-button
- react-divider
- react-image
- react-link
- react-menu

**PROBLEM:** Multiple packages use these v8 dependencies...
- utilities
- dom-utilities
- merge-styles
- react-hooks
- utilities
- react-window-provider
- set-version

**PROBLEM:** These packages are *used by v8*. Assuming we need to have a strict policy that *v8 released packages must NOT depend on alpha/beta things*, we'll either need to major release these packages or remove v8's usage of them. (Note that if we keep the deps but major release as 9.x, this will create problems for an eventual `8.0` sustained branch.)
- react-shared-contexts

#### Not ready for beta

Components:
- react-cards
- react-checkbox
- react-flex
- ??react-focus??
- react-slider
- react-tabs
- react-text
- react-toggle