cypress-io/cypress

Convert and consolidate all core-* repos into a Monorepo™

Closed this issue · 2 comments

brian-mann commented

Cypress is currently spawned across nearly two dozen repos and it has become unbearable to keep them all together. We see no real value in publishing separate core-* packages to npm because they are unusable outside of the Cypress context.

We are going to instead consolidate all of these into one monorepo which means we don't have to worry about npm linking different repos, different braches, managing different issues, etc.

This will make it much easier for our own development team, and of course works well as part of our larger overall goal and strategy when it comes to open source. We want to make outside contributions as simple and painless as possible.

Here's an in depth summary of the idea:

Cypress Monorepo

Why?

  • We no longer have to worry about keeping a dozen different repos in sync
  • Branching happens and applies to all projects once, its impossible to get out of sync
  • No more pulling from a dozen different repos
  • No more having 10 tabs open building 10 different projects
  • Enables easier setup which makes it easier for developers (external or internal) to contribute
  • A single issue tracking repo which avoids the problems of: "should i open an issue here or in another repo?"
  • A single repo where all the stars will go which avoids dilution
  • It becomes much easier for the community to track updates and code changes
  • Setting dependencies becomes sane. Example: setting branched driver and server peer dependencies would otherwise be impossible

Tradeoffs (negative)

  • All tests get run in CI in bulk which means a single failure could be in any package
  • Bigger / more intimidating repo size
  • ? what else ?

What goes in it?

  • Code that is not re-usable in other projects or is not useful to the community in any context outside of Cypress
  • Code that in order for it to be updated a new Cypress version would be ‘cut’
  • Examples: https-proxy, extension, launcher, runner, reporter, desktop-gui, electron, cli, driver, server

What does not go in it?

  • Example: cypress-adapter-node does not belong in the monorepo because it can be distributed without causing an update to the desktop application such as bug fixes, enhancements, etc
  • Example: cypress-example-kitchensink should run in its own CI environment and thus requires a separate repo
  • Example: cypress-plugin-socket-io can be independently updated and downloaded from within Cypress along with issues open specific to its functionality
  • Example: cypress-api because its a separate service which can be updated independently and its also private code
  • Example: cypress-releaser because its a common shared lib used by many independent projects and could be useful outside of just Cypress

How should code be organized?

  • in cypress/packages/...
  • Each should have a package.json + readme.md
  • Each should be named with cypress-core-* since they are part of the core cypress product

Should documentation go in there?

  • No because documentation can be released independently of cypress desktop app

What about packages which require building?

  • There should be a cascading npm start command which auto invokes the sub start commands

What about tests?

  • Tests will be written independently in each package but able to be run from a single npm test command
  • Additionally we should be able to pass a flag to npm test which filters the tests and only runs those applicable to a single package. TEST_ONLY=runner npm test
  • We will store all e2e tests (which test comprehensively across all packages) in the root cypress/spec directory, but all other tests unit and integration will go underneath each appropriate package.

What about distribution?

  • We will NOT publish sub packages to npm or version them independently.
  • We could either omit the version number or simply bump them all at the same time to the same version.
  • There will only be a single master changelog.

Changes

  • rename cypress-core-icons to cypress-icons since this is reusable outside of cypress and can be updated independently without issuing a new version of cypress
  • rename cypress-core-releaser to cypress-releaser for the same reasons above
jennifer-shehane commented

The code for this is done, but this has yet to be released. We'll update the issue and reference the changelog when it's released.

brian-mann commented

Fixed in 0.20.0