Brave-UI versioning strategy

[petemill]

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 ([Umbrella] Brave-UI: Split cross-functional publishing #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]

Short term brave-ui version branching

State

• Brave-ui is published to npm as version 0.32.3
• Brave-ui has core-58-x branch which is on 0.32.2
• Brave-core has master branch which has package.json with brave-ui locked at 0.32.3
• Brave-core has 0.58.x branch which has package.json with brave-ui locked at 0.32.2

Process for 1 change

1. Dev lands update to “brave-rewards settings UI” in brave-ui master
2. Dev publishes new npm version of brave-ui: 0.32.4
3. Dev updates brave-core master package.json to brave-ui 0.32.4
4. Dev asks for uplift to Beta channel 0.58.x via tag on PR in brave-ui
5. Uplift Reviewer gives uplift permission in brave-ui
6. Dev picks PR commit to core-58-x branch in brave-ui
7. Dev publishes core-58-x brave-ui branch to npm: 0.32.4-core-58-x.1
8. Dev updates brave-core 0.58.x package.json to brave-ui 0.32.4-core-58-x.1
   • Brave-core PR against 0.58.x branch?

Process for next change

9. Repeat steps 1-6
10. Dev publishes core-58-x brave-ui branch to npm: 0.32.4-core-58-x.2

Refactored less-overhead solution

Implementations are moved in to repo where they are used - mostly brave-core.
(If a layout is needed by other products, it could be NPM published from brave-core, or a dependency on brave-core from that product created)
Storybook site auto-published for each brave-core PR so that UI changes can be easily reviewed.
Only shared UI components and foundation goes in brave-ui. Uplift strategy same as “Short term” strategy above, but should happen much less frequently!
And cut out npm.

[bbondy]

I'd like to propose this workflow:

1.

We init brave-ui with these branches created from master:
0.57.x
0.58.x
0.59.x
master

2.

We update brave-core's package.json on 0.57.x to point to the latest SHA from brave-ui's 0.57.x
We update brave-core's package.json on 0.58.x to point to the latest SHA from brave-ui's 0.58.x
We update brave-core's package.json on 0.59.x to point to the latest SHA from brave-ui's 0.59.x
We update brave-core's package.json on master to point to the latest SHA from brave-ui's master

3.

We update https://github.com/brave/brave-browser/wiki/Brave-Release-Schedule#how-to-do-branch-migrations so that it indicates that when a migration happens we should create a new brave-ui branch accordingly.
Also make sure the new brave-core branch's package.json is pointing to the new branch on brave-ui's SHA.

4.

brave-ui dev always happens to master only, but you uplift to wherever you need with PR approval. Approval happens on brave-core package.json updates in brave-core and not on brave-ui.

[petemill]

@bbondy I'm just seeing if we can skip the npm publish process and go with something like your approach as the one I outlined is definitely more complex than we would like. But for clarity sake, as discussed here's the workflow that does not require a code / build process change that I outlined in the format that you did:

1.

We init brave-ui with these branches created from master:
core-0.57.x
core-0.58.x
core-0.59.x
master

2.

We keep brave-core's package.json on 0.57.x to point to the latest npm release number from brave-ui's 0.57.x: 0.32.1
We keep brave-core's package.json on 0.58.x to point to the latest npm release number from brave-ui's 0.58.x: 0.32.2
We keep brave-core's package.json on 0.59.x to point to the latest npm release number from brave-ui's 0.59.x: 0.32.3
We keep brave-core's package.json on master to point to the latest npm release number from brave-ui's master: 0.32.4

3.

We update https://github.com/brave/brave-browser/wiki/Brave-Release-Schedule#how-to-do-branch-migrations so that it indicates that when a migration happens we should create a new brave-ui branch accordingly. the package.json can be left as-is since it will be locked to a version

4.

• brave-ui dev always happens to master only
• devs uplift to whichever brave-ui branch they need with PR approval. Approval happens in brave-ui PR.
• Once approval given, dev publishes to npm with the version in the format [branch-frozen-version]-[branch-name].[uplift-version-number]
  • The second uplift for 59.x would be published to npm as 0.32.3-core-59x.2. This version number is saved to brave-ui package.json in brave-ui core-59x branch.
  • Brave-core package.json on branch 0.59.x updates brave-ui reference to 0.32.3-core-59x.2 which would previously have been 0.23.3-core-59x.1

[petemill]

Let's go with @bbondy 's workflow since with brave/brave-core#1025 we can have direct-to-github and skip the npm versioning complexity entirely.
We'll keep package.json for now vs using DEPS file, as npm better supports some future workflows around a brave-core storybook and folding in most of the brave-ui feature code to brave-core. However, we can easily revisit using DEPS file later with a small code change - this process would largely stay the same.

Brave-ui branch names would be brave-core-0.58.x, etc

[petemill]

Keeping open until we get uplift approval to 0.58.x, until we do that we're at risk of non-uplift-approved things from brave-ui getting in :-)

[rebron]

@petemill brave/brave-core#1025 (comment) Looks like this got merged. Can you close this issue or is there anything else needed?

[petemill]

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

[petemill]

Branching process wiki updated

[petemill]

Future enhancements at #2335