element-web/docs/monorepo.md

Monorepo

Some words about the structure of monorepo we are using here.

Structure

The monorepo is focused around multiple Typescript projects coming together to form an Element Web & Element Desktop app. Some of the underlying typescript projects are useful for re-use elsewhere, e.g. @element-hq/web-shared-components is reused by https://github.com/element-hq/aurora.

• apps - this directory holds the apps we build, element-web & element-desktop
  • Things in here are not published to npm
  • Things in here have very non-standard publishing steps, e.g. Element Desktop .deb ships via reprepro.
  • Things in here are in lock-step versions with each other
  • Things in here are represented as a group in Immutable Github Releases
  • Things in here support pre-releases & hotfixes
• packages - this directory holds some npm packages we maintain in order to build the apps
  • Things in here are published to npm
  • Things in here respect SemVer
  • Things in here are independently versioned
  • Things in here have a very simple publishing stage of pnpm publish
  • Things in here do not support pre-releases & hotfixes
• modules - this directory will hold some Element Web/Desktop modules we maintain in order to add environment-specific functionalities atop Element
  • Things in here are not published to npm

Branches

• develop - this is the default branch and should always be buildable, this is what developers use as a base branch for their pull requests
  • Deployed via CD to develop.element.io
• #TODO should we just use short-lived release branches? We'd need to effectively interlace them for the various packages which feels messy
• staging - this branch is used to build the latest/next release.
  • During a normal release cycle, develop is merged into staging to "cut" a release candidate
    • Additional changes such as version bumps & changelogs are committed on top
  • During a hotfix/security release, changes are directly cherry-picked to staging to "cut" a release based on the last release rather than develop
  • When a release is finished, i.e. we've shipped the final release for a given version, we merge staging->develop to maintain continuity
• backport/* - these branches are used for cherry-picking entire pull requests from develop to staging, either to patch a release candidate, or to perform a hotfix release
• <username>/* - these feature branches are used for development, and may branch off develop or another feature branch

Tags

• v* - these tags are used by the releases shown in the Github Releases UI, as in, the overall app release group
• <package>@* - these tags represent the release state of an individual npm package from the packages/* dir

Ultimately, the treatment of the 3 types of submodules we host in this repository is quite asymmetrical but this is by design, to simplify processes around projects which do not need the complexities of element-web & element-desktop.