Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

馃帀 From Many Repositories to a Monorepo 馃 #768

Closed
dannyrb opened this issue Aug 14, 2019 · 1 comment

Comments

@dannyrb
Copy link
Member

@dannyrb dannyrb commented Aug 14, 2019

馃憢 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:

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 comment has been minimized.

Copy link

@stale stale bot commented Sep 4, 2019

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.

@stale stale bot added the Stale 馃 label Sep 4, 2019
@stale stale bot closed this Sep 11, 2019
@galelis galelis unpinned this issue Oct 17, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
2 participants
You can鈥檛 perform that action at this time.