🎉 From Many Repositories to a Monorepo 🤖

[dannyrb]

👋 Quick note! If you use or find this repository helpful, please take the time to star this repository. It's a silly metric that doesn't mean much, but it makes me feel warm inside.

🚀 Monorepo (One Repo)

Today we're rolling out a pretty big change. We're combining our many repositories into a single repository (known as a Monorepo). In practice, this means we'll be archiving the following repositories:

• OHIF/react-viewerbase
• OHIF/ohif-core

And re-homing them in this repository. You can find them and other projects crucial to the OHIF Imaging Platform in the following directory structure:

. # Repository Root
├── extensions              #
│   ├── _example            # Skeleton of example extension
│   ├── cornerstone         # 2D images w/ Cornerstone.js
│   ├── dicom-html          # Structured Reports as HTML in viewport
│   ├── dicom-microscopy    # Whole slide microscopy viewing
│   ├── dicom-pdf           # View DICOM wrapped PDFs in viewport
│   └── vtk                 # MPR and Volume support w/ VTK.js
│
├── platform                #
│   ├── core                # Business Logic
│   ├── i18n                # Internationalization Support
│   ├── ui                  # React component library
│   └── viewer              # Connects platform and extension projects
│
├── ...                     # misc. shared configuration
├── lerna.json              # MonoRepo (Lerna) settings
├── package.json            # Shared devDependencies and commands
└── README.md               

The why

Splitting up large codebases into separate independently versioned packages is extremely useful for code sharing. However, making changes across many repositories is messy and difficult to track, and testing across repositories gets complicated really fast.

To solve these (and many other) problems, some projects will organize their codebases into multi-package repositories (sometimes called monorepos). Projects like Babel, React, Angular, Ember, Meteor, Jest, and many others develop all of their packages within a single repository.

As we've continued to shift from a simple viewer to a viewing platform with support for an ever growing number of extensions, we've found authoring changes that touch multiple libraries to be the single largest hurdle to onboarding new community members. Our hope is that these changes make it easier for new users to get started, and for old users to operate even more efficiently than before.

The what

Development and distribution should largely feel very similar, only now with the added convenience of being able to publish new features across multiple projects with a single pull request.

# One time command to enable yarn workspaces
yarn config set workspaces-experimental true

# Business as usual
yarn install
yarn run dev

Now, changes to any project in platforms/* or extensions/* will be reflected in the development experience. Commits scoped to a single project with conventional commit syntax will update each package's version appropriately when merged.

And perhaps most importantly, yalc (or npm link) only needs to be used to link dependencies that are outside of this monorepo.

Gotchas

If you want a deeper understanding, I recommend checking out Lerna's Repository (the tool we're using to manage our monorepo's versioning and releases), and the Yarn Workspaces Docs. Some changes that may be non-obvious:

• Most dependencies, across all projects, are hoisted and deduplicated. They live in a node_modules in the repository's root directory.
• All/most devDependencies are no longer specified in each project's package.json, instead, they're aggregated in the package.json at the root of the repository.
• All of our projects use or extend configuration files that live in the repo root:
  • Jest, Babel, ESLint, WebPack, Prettier, etc.
• When developing, packages that can by symlinked from projects in the monorepo are.

Moving forward, and how you can help

To get this out the door and minimize issues caused by merge conflicts across multiple repositories, we've moved rather quickly. Depending on our availability, it may take a few days or weeks for us to update documentation, fix/improve automated deployments, and work out ideal development workflows.

You can help by:

• Remaining patient and supportive as we work out kinks 🙏
• Reporting any issues or regressions you experience 🐛
• Requesting and contributing documentation for anything that is non-obvious 📚

You may have missed...

A lot of development happens between announcements like this that we don't publicize. Keeping your viewer in sync with the OHIF Viewer buys you awesome enhancements like:

• Removal of bootstrap dependency
• Improved labeling workflow
• Simplify cornerstone-wado-image-loader usage so codecs and worker files no longer need to be co-hosted alongside application
• Addition of end-to-end tests to smoke out issues before a release is cut
• Simplify script-tag usage of the ohif-viewer to a single required include and initialization step
• Many new VTK/MPR features and fixes
• Support for fuzzymatching searching
• Several new hotkeys/commands
• Many other small fixes and enhancements

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.