Discussion: separate repos vs monorepo

[paulirish]

There are a few efforts that make sense to be published independently and consumed by other projects not using the entire Lighthouse stack:

• manifest-parser
• lantern simulator
• the robots.txt validator
• streaming trace parser & trace writer
• proposed JSON-ld validator
• chrome-launcher (lives in separate repo)
• speedline

There are definite benefits for projects like these to be available independently. The primary benefit is that, availability as a standalone module increases likelihood of use by other projects, and that increases likelihood of receiving bug reports, fixes, features and maintenance.

---

At the same time, we've also found challenges working with separate repos:

• issues/pull requests don't fall into the same UI, so it's much easier that they're ignored and not prioritized.
• Each change that touches LH and a "child" project now requires 2 PRs and 2 review cycles.
• After the change in the child project is landed, its package must be released (publicly) for the parent to use the new commit.
• harder to reuse tooling (unit testing, CI projects, changelog generation)

These reasons are what leads me to favor keeping projects within the mono-repo.

However the less that we expect code changes/issues/reviews that affect LH, the more it is reasonable to live in it's own repo.

---

@brendankenny @patrickhulce thoughts?
@rviscomi @kdzwinel what are you thinkin?

[patrickhulce]

I think splitting out reusable functionality and distributing it makes a lot of sense, so big +1 to that. As for how we do that, I'd also vote monorepo if we make the effort to be consistent with the ecosystem and adopt tooling that will help us with the additional burden. When a module seems to become popular and independent enough of lighthouse, then it makes sense to split it out into it's own repository where issues/PRs can be managed separately, but until that point, I think the extra burden of maintenance is too high for the sake of hypothetical other consumers.

My ideal setup would be that we turn this into lerna-style monorepo and publish some of our core pieces under a @lighthouse org. Example of what it might look like below.

lighthouse
 |- packages
      |-lighthouse (published as lighthouse like today, bundles everything)
      |-core (published as @lighthouse/core, might depend on other bits)
      |-cli (published as @lighthouse/cli
      |-lantern (published as @lighthouse/lantern)
      |-logger (published as @lighthouse/logger)
      |-manifest-parser (published as manifest-parser)
      |-robots-validator (published as robots-validator)

lerna+yarn workspaces really eases a lot of the pain of having to make changes in multiple places at once, bumping dependencies on your own modules, etc. It also make it pretty seamless to automate publishes as well which would be nice to get a lighthouse@next published fresh off master every day :D

[brendankenny]

I think the easiest decision to make is to spin the submodule out of our repo when it will have a clear owner who maintains the project for more reasons than just as a Lighthouse dep. aXe is really great because we can hand off bugs and get pinged when we can bump the dep.

The contrast is chrome-launcher, where it's hard to care about proposed fringe features since Lighthouse is already served pretty well, we're the maintainers anyways, and the only person to ping us to bump the dep is ourselves :)

There's also the question of scope. I think having a project within Lighthouse implies that it's a part of Lighthouse that might be useful independently, not just that it's a thing that the LH team also maintains and part of it is used in LH. How much bandwidth can we spare for these projects when/if they expand beyond things that LH contributors care about? Sometimes new features are complicated and subtle, and it can take a good deal of research before even knowing if a PR is a good idea, let alone implemented well.

There's also a question of complexity of implementation. Some of these things (e.g. trace parser, manifest parser, robots.txt parser?) are very bounded in scope and can basically be "finished", only adding new things if/when the specs update or bugs need to be fixed. That really lowers the bar on how often we need to open PRs against them/bump the version in LH.

• trace parser and writer seems like it could fall well within the notion of "part of LH that could be useful on its own" without much scope beyond that
• manifest parser is as well if LH is still considered the authority on PWA verification (there's not really anything in web app manifests that LH doesn't care about, even if to just flag a validation error)
• lantern simulator I see more as a component of LH than a separate project, but it is possible it could be useful to projects to depend on in the future
• JSON-ld and robots.txt validators I'm not sure about, though. What's the scope for them beyond what LH cares about? If it's large, it seems that they should be external (and it seems like @rviscomi is optimistic that it could have maintainers outside our team)

[brendankenny]

We also don't want to overdo architecture organization for the sake of itself. I think that there are definitely productivity improvements we could make here, but LH as currently designed is pretty tightly coupled, and we make decisions all the time that adds to that. We shouldn't have our project/build infrastructure pretend otherwise or we'll just end up with impedance mismatch in the other direction :)

[rviscomi]

I'm amenable to a monorepo approach with independent modules. That addresses my biggest concern about downstream consumers. I still find it cumbersome that anyone who wants to spin it off would need to fork the entire LH codebase. Or would that not be the case?

JSON-ld and robots.txt validators I'm not sure about, though. What's the scope for them beyond what LH cares about? If it's large, it seems that they should be external (and it seems like @rviscomi is optimistic that it could have maintainers outside our team)

I guess it's similar to chrome-launcher in that it's designed to fit the needs of Lighthouse, but is expected to be a generalized enough solution for other applications. I hope to have it able to validate all forms of structured data like JSON-LD, open graph, microdata, etc - all things LH will care about and validate - but other consumers may want finer controls. As for who will maintain it if external, I'm more hopeful than optimistic that it'll be community-maintained. Haven't explicitly asked anyone yet.

So I think we have consensus that we can start developing the SD validation within the LH repo in a way that enables the module to be published independently. If and when it gets big enough, we can spin it out as @brendankenny suggests.

[paulirish]

So I think we have consensus that we can start developing the SD validation within the LH repo in a way that enables the module to be published independently. If and when it gets big enough, we can spin it out.

Groovy. SGTM.

---

Closing this issue, but it was super valuable to record our thoughts here. Thx ya'll!