Brave-UI versioning strategy

tl;dr. Semver doesn’t work well for brave-ui since it contains different projects and is consumed by multiple targets with their own semver strategies.

We’ve determined some improvements are necessary to how we roll brave-ui updates to various branches of brave-browser (and other Brave projects).

Goals of these improvements:

1. Avoid bringing in unwanted brave-ui updates to versioned brave-core branches (Beta branch, etc)
2. Preserve master brave-ui updates automatically continuously landing in master brave-browser branches
3. Preserve other projects being able to consume all of specific brave-ui updates as desired.

Right now the main problem is that we use straight-forward semver npm publishing for brave-ui, and use it to publish not only the core design tokens (components, themes, etc) but also the actual UI used by the products (Brave Desktop, Brave Android, etc). Multiple UI areas are worked on at the same time. If it is determined that Beta branch of Brave Desktop needs a fix to a specific UI implementation contained within Brave-UI, then we are often simply rolling the latest version of brave-ui in to that branch, pulling in a number of non-related UI changes.

Therefore the aim is simple:

• Versioned branch of brave-core should only accept brave-ui changes that are explicitly desired

How?

Some of the ideas we’ve talked about:

• Keep semver, and release minor / patch version updates
  • Con: This doesn’t work well when there are multiple dependent projects or even sub-projects within brave-core (rewards, shields, welcome, ntp) since it’s the project that determines what should be changed, not brave-ui’s semver. Therefore, this would still result in non-related UI changes being bought in to a project.
• Use project-versioned branches and npm version ‘strings’ for brave-ui
  • e.g. brave-core-58 branch gets published to npm as brave-ui x.x.x-brave-core-58x.1
• Publish under different npm project names (@brave-ui-core-58, @brave/ui-core-57, @brave-ui)
  • Still requires project branches in brave-ui
• Split brave-ui up so that the shared tokens and components are in it but the ‘features’ and actual UI layouts are in a separate repo (https://github.com/brave/brave-browser/issues/2335)
• Don’t use npm in brave-core - go directly to a github commit via package.json or DEPS
  • This is kind of possible since we don’t need the pre-generated JS in brave-core, we can go directly to TS
  • BUT we do depend on the npm pre-publish build process wrt import paths. We’d need to change them all (at least in brave-core).
• Some combination of above, such as project-branches combined with direct-to-github for brave-core only

It seems to me that the best approach is going to be use a brave-ui project-based branch for uplifting and use the prerelease tag feature of npm semver strings. But please comment with alternatives or other scenarios that expose issues.

IMO we should also split the implemented features from the core shared components, either putting them in the repo they belong in and then benefit from the versioning of that repo (more preferred), or another repo (less preferred).

Scenario 1

Latest brave-ui master version is 0.10.1, Brave-Core Dev branch (0.58.x) is using 0.9.3, Brave-Core Beta branch is using 0.9.2, and a UI change wants to be uplifted to Brave-Core Dev.

• We create a brave-ui branch specifically tracks the Brave-Core Dev branch features, based on the 0.9.3 tag - called Brave-Core-58x.
• We cherry-pick the brave-ui fix / feature from master to Brave-Core-58x
• We then publish to npm under the version “0.9.2-brave-core-58x.1”
• We modify the package.json in Brave-Core Dev branch to point to this version.

[petemill]

Keeping open to remind myself to update the branching process wiki today

[petemill]

Future enhancements at https://github.com/brave/brave-browser/issues/2335