💡 How to rollout of breaking changes across @octokit packages

[gr2m]

Now that we are about to conclude rolling out several breaking change across @octokit I'd love to take the opportunity to reflect and see how we can improve the process in future. It was easier in the past when I was the only maintainer, but I see now that there is a lot of knowledge that I haven't really written down. I'm sorry the rollouts created so much friction.

This is a general question of monorepo vs separate repos to me. I remain strongly in the separate repos camp, and I'd like to take the opportunity to come up with tooling that will remove this kind of friction that might not have occurred if the JavaScript Octokit was a monorepo.

I'm not sure how it would like like, but I could imagine an automation that is triggered by a breaking release change (including in beta branches) and creates a "rollout" issue with a check list of all packages within the @octokit org that depend on the current package, and puts them in a useful order. I think the "breaking change rollout" issue should be in a central repository, and would ideally self-update as dependencies are updated in the respective repositories. I hope what I'm saying makes sense, I can create more of a technical design document for it. I'm interested in it as I'd love to find a generalized solution for this, to help other projects that run into the same challenge as us.

But I'm sure there are other ideas that would help, hence the discussion :) @octokit/js @octokit/js-community

[kfcampbell]

@gr2m do you mind explaining the initial thought behind the monorepo vs. separate repos decision (or pointing me to somewhere I can read about it)? I'd love to have some additional context.

[gr2m]

A little bit of the history of the JavaScript SKD is captured in this blog post: https://github.blog/2020-04-09-from-48k-lines-of-code-to-10-the-story-of-githubs-javascript-sdk/

We started out with a big module that we adopted from the community, decomposed it into small modules, then recompiled it into @octokit/rest, which still is very simple today: https://github.com/octokit/rest.js/blob/688f86a768581fbc411d1f34210fd3d1e01bbdf6/src/index.ts

We could have used a monorepo approach, but I was never a fan. There are many reasons for it, but the two reasons that stand out for me is that having different versions for packages in a monorepo is a huge pain, and having smaller modules makes these modules easier to document, test, and most importantly to me, contribute to. Also with separate repositories, maintainership/ownership is easier to distribute.

The was no deliberate decision at that point in time, I just made the decision, as I was working on it by myself when I created the JavaScript Octokit for GitHub 🤣

[kfcampbell]

having different versions for packages in a monorepo is a huge pain, and having smaller modules makes these modules easier to document, test, and most importantly to me, contribute to.

I'm totally with you on the first point, but I'm a little lost on the second. From my perspective, the overhead of small repos is pretty significant: we end up managing separate CI runs, dependencies, branch protection policies, documentation, etc. for our ~50 repos, which means a lot of context-switching is required for users and maintainers. What are your thoughts on that overhead?

[gr2m]

What are your thoughts on that overhead?

1. I have spend little time on CI environments, they don't change that often
2. When they do in a way that I want to update all at once, I write an @octoherd script which scales endlessly

Having separate documetnation is a plus. I don't see it as overhead. I want to have each module properly documented.

[oscard0m]

Thanks @gr2m for opening this discussion. I hope we can get some actions as an outcome to improve the DevEx and reduce friction in Octokit's JS Ecosystem.

I would like to use this message also to say thanks to @wolfy1339🎖️ @kfcampbell🎖️ @nickfloyd🎖️ and @gr2m🎖️ for the great teamwork with this latest release. Congratulations 🍾

---

About internal dependency updates

💟 What I love about our current system as a contributor

• I get immediate feedback if my PR is good to be merged: The CI takes a decent amount of time on give feedback to the author of a PR.
• A merged PRs is released immediately: We don't need to wait for an alpha/beta and wait for those changes to be released in a few days/weeks in a stable version. Also semantic-release is automating all the work: publish on npm, release notes...
• Automated dependency management: I like Renovate. It saves a lot of work for the maintainers being up to date, specially for security patches.

👿 Problems I've faced as a contributor

• Internal dependency noise by Renovate: Lots of GitHub notifications, and sometimes there's not much value the reviewer/s add.
• Regressions not caught by our CI/CD: Some regressions are not caught by our CI, we end up releasing a version with that bug and, if we don't catch it on time, we spread the bug to other internal packages with Renovate.
  • see Automerging renovate PRs .github#45
• Missing Integration tests: When adding a new change in package A, there's no easy way to see how that change will impact packages B, C... which have package A as an internal dependency.
• Repeated maintenance work across multiple repositories: Sometimes automated with Octoherd, sometimes manually done. In my case, I end up having most of the JS Octokit repos in my local machine and applying the same patch/feature one by one.

Open questions

Before coming up with some proposals and doing some research¹, I would like to know:

1. Is the monorepo 🆚 multirepo discussion open?
2. Do you know any good multirepo OSS projects in JS/TS we can take a look into as a reference?
3. Do we have a way to get stats about Octokit's Release history (number of breaking changes, regressions...)?. I think it would be interesting to figure out some outcome/actions from there.

Footnotes

1. vite is doing something interesting which could be an inspiration for us https://github.com/vitejs/vite-ecosystem-ci. Nuxt (https://github.com/nuxt/ecosystem-ci) and Svelte (https://github.com/sveltejs/svelte-ecosystem-ci) have forked it. ↩

[wolfy1339]

Babel is a good example of a monorepo.
They used to be multirepo

[gr2m]

• Missing Integration tests

That is a valid point, and it's something I always wanted to work on. Ideally we would want to run the tests of all dependents up the tree. E.g. if there is a pull request to @octokit/endpoint that changes production code, I'd love if we would run the tests of @octokit/request, @octokit/core, and octokit. I don't think this would be hard to setup, and I think it could be zero config.

[gr2m]

1. Is the monorepo 🆚 multirepo discussion open?

I would like to not have monorepo vs multirepo discussion here. I opened this one specifically to learn about the friction points of the rollout of the most recent breaking changes, maybe other friction points we see, because I would like to address them. Once they are addressed as good as we can, I'm happy to have an extended discussion about monorepo vs multirepo for @octokit.