Combine repos

[mayank99]

Problem

Currently, iTwinUI and iTwinUI-react are two separate repos. The initial idea behind this was that the CSS should be usable independently of React. But that only requires separate packages, not separate repos. Having packages that are often changed together live in separate repos causes friction. Every CSS change needs to be released and propagated to React, which is a slow, blocking process. Even after it's consumed, we sometimes find that we need to make more changes which means redoing this whole cumbersome process.

Additionally, our repo names are confusing for users who want to create issues/discussions. They are even confusing for ourselves when it comes to backlog management. Issues often need to get moved between repos. PRs sometimes get "lost" after merging in CSS, which results in CSS changes that don't get consumed in React for long periods of time, if at all.

Lastly, our changelog and release process, while better than something entirely manual like we had before, is a bit problematic. Conventional commit requirements have been hard to follow. PR titles are usually too small to be useful as changelogs. I personally often find myself manually expanding the changelog text when releasing. And the iTwinUI repo is not multi-package aware so there is currently no way of automating releases for itwinui-variables.

Solution

Combine the monorepos and merge their git histories. Specifically, iTwinUI-react will be merged into iTwinUI. Since we are already using turborepo in both repos, a lot of this should be very straightforward to get running and I don't expect many merge conflicts.

The single monorepo will contain the code for all three packages (itwinui-variables, itwinui-css, itwinui-react) as well as all the demos, tests and examples. changeset will be used for a release/changelog process that is more suited for multiple packages. The old repo will be archived.

Estimated time: one week. This could be done over the holidays when we are allowed to have some downtime.

Benefits

• Better developer experience. All related changes can be made and previewed together. Saving a .scss file will instantly reflect all the way over in storybook. Faster feedback loop also means less chance of missing something, and no need to go back and forth or wait for releases. I expect we will likely ship things faster as a result.
• Better repo management. Users don't need to keep track of multiple repos. Non-technical users (e.g. UX team) know exactly where to look. Issues don't need to be moved back and forth.
• Better changelogs and release process. changeset's philosophy is to make changelogs part of the PR process, so there is no burden on the person making the release to expand changelogs. Additionally, it will be able to manage the release of multiple packages, as it's specifically designed for monorepos.
• Less duplication. Readmes, prettier configs, eslint, issue templates, PR templates, github workflows can all be shared so we don't need to make the same change in two repos.
• More flexible. This also opens the door for us to make drastic changes in the future if we so desire. We could add layouts and icons into this repo if we wanted. We could split up react into multiple packages (e.g. having Table in a separate package). Since scss and react live in the same repo, we could potentially do some build-time shenanigans like using mixins to generate unique classnames that don't conflict between major versions.

Downsides

• Need to spend some time getting the CI/CD process working (build/test/deploy/release).
• There could be some downtime while waiting for this migration.
• Uncertainty. We might not have considered something now and run into an issue later.

Imo the benefits far outweigh the downsides.

Action items

• Complete any pending PRs in iTwinUI-react and put a freeze on new PRs.
• Merge iTwinUI-react into iTwinUI and keep git history
• Update turbo pipelines/tasks to get all parts working (build/tests/dev)
• Update github-actions to get build/test working
• ci: Setup changesets for release automation #875
• ci: Deploy storybook on gh-pages #937
• Move all open issues from iTwinUI-react to iTwinUI
• Copy (but not remove) everything from the iTwinUI-react wiki to iTwinUI wiki
• Create gh discussion to announce iTwinUI-react is archived (iTwinUI-react has moved iTwinUI-react#1001)
• Hosting v1 storybook iTwinUI-react#1000
• Archive iTwinUI-react repo

[mayank99]

Reposting #868 (comment) here for visibility:

• configs maybe can be moved outside packages
• createComponent scripts can be combined to create both css and react files
• copyrightLinter script can be combined.
• easier/less confusing way to "approve" images for css/react from root
• update and validate CONTRIBUTING guide
• update and validate issue/PR templates
• chore: Fix errors in astro workspaces #929