Multiple repos vs Monolithic repo

[Ricky Chien]

*Multiple repos vs Monolith repo*

Paris work week is happening during this week, we're going to have some
discussions about how to go for our repository strategies. Here are some of
my thoughts and surveys for these two major strategies.

*Background*

Based on technology and language we use, npm, Semantic Versioning
<http://semver.org> and webpack are some awesome approaches which really
fit both repo strategies.

*NPM*

Flat dependency tree is an amazing feature in npm v3
<https://docs.npmjs.com/how-npm-works/npm3> , which let you installs
dependencies in a flat structure rather than in a nested way. It means that
duplicated modules in node_modules has gone away unless someone requires a
different version of the same module.

*SemVer*

Follow the rule of semantic versioning (major.minor.patch), we can maintain
and upgrade our packages in a safe way without breaking every repository.
New workflow based on SemVer is growing, like semantic release
<https://github.com/semantic-release/semantic-release>, which can help us
to speed up package releasing.

*Webpack v2*

As you may know, webpack has upgraded to v2 for a while. After migrating to
v2 we can get more benefits like Lazy Loading - React
<https://webpack.js.org/guides/lazy-load-react/> and Tree Shaking
<https://webpack.js.org/guides/tree-shaking/>.

The trouble of bundle duplication can be mitigated through the combo of
npm, SemVer and Webpack2. Here is a good demo illustrates how to solve
duplication with a webpack plugin RootMostResolvePlugin
<https://github.com/webpack/webpack/issues/985#issuecomment-260230782> with
a simple configuration
<https://github.com/aurelia/skeleton-navigation/blob/3eb4d3fa65b60731493c79235e547792324cc3e7/skeleton-typescript-webpack-experimental/webpack.config.ts#L367-L370>
.

Above technologies can work out some critical issues no matter we adopt
multiple repos or monolith repo. Following comparison is about advantages
and disadvantages between multi-repos and mono-repo structures.

*Multiple repositories*

Standalone repository for each panel (inspector, debugger, console,
netmonitor...etc). One central repository which provides a basic build
configuration and being able to opt-in / opt-out all sub-repos. For Github
issue page, unclear component bugs goes to the central repo and clear
component bugs goes to each sub-repo's issues page.

Pros

- Clear ownership for each repo
- Lightweight repository
- Mitigate development pain like we had to download and build entire
m-c but merely touch devtools folder in most of the time.
- Project size will be bloated and git command execution time
will slow down.
- Gaia <https://github.com/mozilla-b2g/gaia> hit this bloated
project soon when it came to becoming monolithic repo.
- High flexibility of dependency upgrade
- Each sub-repo has a chance to upgrade frameworks / libraries as
needed.
- For example, we can start to upgrade React version from an
independent sub-repo throughout other sub-repos step by step without
breaking others.

Cons

- Unmanageable Github issues
- Bad for managing and triaging issues across multi-repos (ex: move
incorrect issue to correct issue page).
- Cross-repos changes
- Significant overhead will be added when we need to make change to
many sub-modules.
- Maybe it boils down to one thing - we should do more module
extraction.

*Monolith repository*

One Github repo and issue page, it's likely to adopt current
mozilla-central/devtools structure for our front-end (client) code. We can
continue to use shared folder as well.

Pros

- Manageable Github issues
- Certainly, there is only one place to keep all issues and it's easy
to triage issues cross sub-modules.
- A centralized Github repo
- Higher repo star count and attention in community
- Easy to count up to contributors cross all sub-modules
- Cross-repos changes
- In contrast with the multi-repos, one pull request can cross
sub-modules.
- For example, it will be very easy to modify code style cross all
sub-modules.
- It will be easy to develop and test features cross sub-modules.
- Shared folder strategy
- So far the shared folder approach has been using nicely for a long
time. We can still adopt this good approach and maintain all components /
modules in shared folder (including Reps, Splitbox, theme...etc).
- Shared component changes is likely to cause cross-repo changes.
This way can reduces overhead of managing submodules workflow.

Cons

- Unclear ownership
- Bloated repository
- Codebase looks more intimidating
- All commit changes will increase quickly, repo sooner will be
bloated.
- Low flexibility of dependency upgrade
- In contrast with the multi-repos, framework upgrade will impact on
other panels since there is only one framework instance. It
would be a risk
to upgrade framework major version for one panel but we have to fix all
issues at once time.

*Possible solution*

Note that there are more and more framework adopted mono-repo like Babel
<https://github.com/babel/babel/tree/master/packages>, React
<https://github.com/facebook/react/tree/master/packages>, Meteor
<https://github.com/meteor/meteor/tree/devel/packages>, Angular
<https://github.com/angular/angular/tree/master/modules>, Ember
<https://github.com/emberjs/ember.js/tree/master/packages>...and others.
However, they aren't following the traditional mono-repo strategic but a
newer solution for mitigating some pain points in mono-repo - *Mono-repo
with multiple packages*.

Lerna <https://github.com/lerna/lerna> is a tool for managing
multi-packages in mono-repo. In that way, we can follow the recommended
structure and create a packages folder for maintaining sub-repos including
all panels, shared components, theme...etc. And I've seeing devtools-core
<https://github.com/devtools-html/devtools-core> that has been adopting
this model as well.

*Issues in Webpack + Lerna*

We should keep an eye on duplicated module issue
<https://github.com/webpack/webpack/issues/3463#issuecomment-272568348>
when combining Webpack and Lerna. It seems that there are still no
agreement in solving this problem at build level or at dependency manager
level.

My feeling is that multi-repos could be the ultimate repo structure but the
pain point of overhead in cross-repo changes is crucial to the project
development, and it is hard to be erased. So that's why there are more and
more projects embracing mono-repo. I think problems like duplicated module
issue
<https://github.com/webpack/webpack/issues/3463#issuecomment-272568348> could
be addressed sooner and later since many projects and companies have moved
to this architecture, and involved with improving tooling.

I'm not going to say mono-repo is the right way to go, but here are some
reasons to tell you why many projects prefer to go this way. So I'd like to
share this background and survey result and open to discussions. Any
feedback and thoughts are welcome :)

[Julien Wajsberg]

my comments about multirepo/monorepo:

*


*

Le 13/03/2017 à 16:42, Ricky Chien a écrit :
> *Multiple repositories*
>
> Standalone repository for each panel (inspector, debugger, console,
> netmonitor...etc). One central repository which provides a basic build
> configuration and being able to opt-in / opt-out all sub-repos. For Github
> issue page, unclear component bugs goes to the central repo and clear
> component bugs goes to each sub-repo's issues page.
>
> Pros
>
> - Clear ownership for each repo
> - Lightweight repository
> - Mitigate development pain like we had to download and build entire
> m-c but merely touch devtools folder in most of the time.
> - Project size will be bloated and git command execution time
> will slow down.
> - Gaia <https://github.com/mozilla-b2g/gaia> hit this bloated
> project soon when it came to becoming monolithic repo.

Gaia never hit the painpoint for me :) (mozilla-central definitely did
though).

Also I believe the devtools code and commit frequencies are
significantly smaller than in Gaia -- I may be wrong though.

> - High flexibility of dependency upgrade
> - Each sub-repo has a chance to upgrade frameworks / libraries as
> needed.
> - For example, we can start to upgrade React version from an
> independent sub-repo throughout other sub-repos step by step without
> breaking others.

In a monorepo we can still have separate modules, and so different
package.json, and so different react versions.

That said, I think we want the same react version throughout the tools,
so that we don't embed different react libraries in Firefox in the end.
This may be another story, but you'll tell me.

>
> Cons
>
> - Unmanageable Github issues
> - Bad for managing and triaging issues across multi-repos (ex: move
> incorrect issue to correct issue page).
> - Cross-repos changes
> - Significant overhead will be added when we need to make change to
> many sub-modules.
> - Maybe it boils down to one thing - we should do more module
> extraction.
>
> *Monolith repository*
>
> One Github repo and issue page, it's likely to adopt current
> mozilla-central/devtools structure for our front-end (client) code. We can
> continue to use shared folder as well.
>
> Pros
>
> - Manageable Github issues
> - Certainly, there is only one place to keep all issues and it's easy
> to triage issues cross sub-modules.

This is a huge + for me. Most often users will file issues in the
top-level project (eg: debugger.html) and if the fix ends up being in a
dependency, this is not nice (although manageable).

> - A centralized Github repo
> - Higher repo star count and attention in community
> - Easy to count up to contributors cross all sub-modules
> - Cross-repos changes
> - In contrast with the multi-repos, one pull request can cross
> sub-modules.
> - For example, it will be very easy to modify code style cross all
> sub-modules.
> - It will be easy to develop and test features cross sub-modules.
> - Shared folder strategy
> - So far the shared folder approach has been using nicely for a long
> time. We can still adopt this good approach and maintain all components /
> modules in shared folder (including Reps, Splitbox, theme...etc).

I think it should be a separate submodule (but inside the same repo).
Like devtools-core we already have :)

> - Shared component changes is likely to cause cross-repo changes.
> This way can reduces overhead of managing submodules workflow.
>
> Cons
>
> - Unclear ownership

IMO ownership is not an issue with any of the scheme. In Gaia (because
you use that example) ownership was clear.

> - Bloated repository
> - Codebase looks more intimidating
> - All commit changes will increase quickly, repo sooner will be
> bloated.
> - Low flexibility of dependency upgrade
> - In contrast with the multi-repos, framework upgrade will impact on
> other panels since there is only one framework instance. It
> would be a risk
> to upgrade framework major version for one panel but we have to fix all
> issues at once time.

Monorepo doesn't necessarily mean monoframework.
if the framework is published with npm, we could still use specific
versions where/when necessary, and not necessarily use the in-tree
framework everywhere. (although it's better if it's possible)


Something that hasn't been mentioned in your list: npm doesn't support
pointing to subdirectories in a git repo. What does it means exactly ?
It means we can't be in the middle of both solutions. I ran into this
recently working with debugger.html, relying on devtools-modules, that's
actually a submodule in the devtools-core repository. I couldn't easily
test a change in a branch in devtools-core without locally `npm
link`-ing the repository.
What's the solution to this ? Either move devtools-module to a separate
repo OR move everything in a monorepo.


So you can see I'm in favor a monorepo with submodules. It's also not a
surprise that, as you mentioned, complex projects are using this scheme.

[rch...@mozilla.com]

On Tuesday, March 14, 2017 at 10:39:54 PM UTC+8, Julien Wajsberg wrote:
> my comments about multirepo/monorepo:
>
> *
>
>
> *
>
>
>
> Le 13/03/2017 à 16:42, Ricky Chien a écrit :
> > *Multiple repositories*
> >
> > Standalone repository for each panel (inspector, debugger, console,
> > netmonitor...etc). One central repository which provides a basic build
> > configuration and being able to opt-in / opt-out all sub-repos. For Github
> > issue page, unclear component bugs goes to the central repo and clear
> > component bugs goes to each sub-repo's issues page.
> >
> > Pros
> >
> > - Clear ownership for each repo
> > - Lightweight repository
> > - Mitigate development pain like we had to download and build entire
> > m-c but merely touch devtools folder in most of the time.
> > - Project size will be bloated and git command execution time
> > will slow down.
> > - Gaia <https://github.com/mozilla-b2g/gaia> hit this bloated
> > project soon when it came to becoming monolithic repo.
>
> Gaia never hit the painpoint for me :) (mozilla-central definitely did
> though).
>
> Also I believe the devtools code and commit frequencies are
> significantly smaller than in Gaia -- I may be wrong though.

I was not aware of this problem in Gaia until I got a chance to develop Gaia on a non-SSD laptop. Running git command is obviously slow than in SSD. But I am not sure that problem will happen in devtools too.

> > - High flexibility of dependency upgrade
> > - Each sub-repo has a chance to upgrade frameworks / libraries as
> > needed.
> > - For example, we can start to upgrade React version from an
> > independent sub-repo throughout other sub-repos step by step without
> > breaking others.
>
> In a monorepo we can still have separate modules, and so different
> package.json, and so different react versions.
>
> That said, I think we want the same react version throughout the tools,
> so that we don't embed different react libraries in Firefox in the end.
> This may be another story, but you'll tell me.

Yes, agree. My feeling is that someday we might want to upgrade our frameworks for getting better performance, supporting new features... The strategic to upgrade frameworks like React or Redux in safety without breaking every piece of code cross devtools modules is important.

Perhaps we can upgrade framework along with a bunch of follow-up patches for upgrading all sub-modules. It will be a large patch / pull request and could block any ongoing features for many panels.

My imagination is that it could be acceptable to keep two duplicated framework versions during migration period, and we can upgrade framework piece by piece like debugger panel can start upgrading to react 16 first and then other panels can follow it.

Agree. It's a good paradigm for mono-repo + multi-packages.

>
> > - Shared component changes is likely to cause cross-repo changes.
> > This way can reduces overhead of managing submodules workflow.
> >
> > Cons
> >
> > - Unclear ownership
>
> IMO ownership is not an issue with any of the scheme. In Gaia (because
> you use that example) ownership was clear.

You're right! Well documentation can also help this a lots. Especially in modern web development, more and more projects are adopting mono-repo + multi-package scheme, so more and more contributors may know how it works.

[Patrick Brosset]

Thank you Ricky for this email, the details about each solution and your
opinion. That helps.
We have been discussing about this a bit yesterday in Paris. One thing we
said is that if/when we move the rest of DevTools to GitHub (what currently
remains on m-c), we would move it to a single repo. But we wouldn't
necessarily want to move the debugger or perf repos back into it. The
debugger repo in particular is benefiting from a lot of attention these
days and we should not break the momentum. There are reasons to believe
that being in its own small/independent repo makes it better for
contributors to participate in the project.
Moving the rest of DevTools to another mono-repo would give us a way to
compare too.

Patrick

On Thu, Mar 16, 2017 at 4:59 AM, <rch...@mozilla.com> wrote:

> On Tuesday, March 14, 2017 at 10:39:54 PM UTC+8, Julien Wajsberg wrote:

> I was not aware of this problem in Gaia until I got a chance to develop
> Gaia on a non-SSD laptop. Running git command is obviously slow than in
> SSD. But I am not sure that problem will happen in devtools too.
>

> > > - High flexibility of dependency upgrade
> > > - Each sub-repo has a chance to upgrade frameworks / libraries as
> > > needed.
> > > - For example, we can start to upgrade React version from an
> > > independent sub-repo throughout other sub-repos step by step
> without
> > > breaking others.
> >
> > In a monorepo we can still have separate modules, and so different
> > package.json, and so different react versions.
> >
> > That said, I think we want the same react version throughout the tools,
> > so that we don't embed different react libraries in Firefox in the end.
> > This may be another story, but you'll tell me.
>

> Yes, agree. My feeling is that someday we might want to upgrade our
> frameworks for getting better performance, supporting new features... The
> strategic to upgrade frameworks like React or Redux in safety without
> breaking every piece of code cross devtools modules is important.
>
> Perhaps we can upgrade framework along with a bunch of follow-up patches
> for upgrading all sub-modules. It will be a large patch / pull request and
> could block any ongoing features for many panels.
>
> My imagination is that it could be acceptable to keep two duplicated
> framework versions during migration period, and we can upgrade framework
> piece by piece like debugger panel can start upgrading to react 16 first
> and then other panels can follow it.
>
> > >

> Agree. It's a good paradigm for mono-repo + multi-packages.
>
> >

> > > - Shared component changes is likely to cause cross-repo changes.
> > > This way can reduces overhead of managing submodules workflow.
> > >
> > > Cons
> > >
> > > - Unclear ownership
> >
> > IMO ownership is not an issue with any of the scheme. In Gaia (because
> > you use that example) ownership was clear.
>

> You're right! Well documentation can also help this a lots. Especially in
> modern web development, more and more projects are adopting mono-repo +
> multi-package scheme, so more and more contributors may know how it works.

> _______________________________________________
> dev-developer-tools mailing list
> dev-devel...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-developer-tools
>