wip: RFC to move away from using current repo as a monorepo

[rawlingsj]

This is an initial proposal taking onboard recent discussions on how we build the wider cartographer ecosystem. It's early stages and aimed to solicit feedback of the general direction going forward.

RFC Text

[netlify]

✔️ Deploy Preview for elated-stonebraker-105904 canceled.

🔨 Explore the source changes: d884618

🔍 Inspect the deploy log: https://app.netlify.com/sites/elated-stonebraker-105904/deploys/61f93ca17086210007260950

[squeedee]

A related issue #436

[squeedee]

Not sure this is a high priority.

1. deploying runnable does mean a fatter controller and unnecessary CRDs today, but that can be mitigated in other ways if required.
2. runnable co-opts a lot of the cartographer runtime, so we'd have to libify cartographer as part of this effort.

I feel like adressing extracting runnable as it's own controller (or the same controller with feature flags to only run where the Runnable CRD is installed) is an orthoganal concern, but this RFC opens up our options for such future discussions.

[waciumawanjohi]

I agree with Rash. It's not clear that "the juice is worth the squeeze" in terms of separating Runnable into a separate repo. As he mentions, there would be non trivial engineering work because Runnable shares code with the other parts of Cartographer. Do we have evidence that

1. A user would like to use Runnable without using supply-chains/delivery.
2. That user is concerned about the overhead of installing supply-chains/delivery with Runnable.

[martyspiewak]

Would it be that much effort to split out runnable? In terms of the underlying code that's shared and called from the reconciler, it's all libified already, no? The runnable repo can still import github.com/vmware-tanzu/cartographer/pkg/... and I would think not much would change.

[squeedee]

In code, no. In docs? maybe, in tooling, plenty? The argument isn't about the size and shape of the work, the argument is the need to even consider it at this point. Perhaps I'm being too "agile" in wanting to focus on immediate pain points, of which there are enough to accept work to split out docs and be prepared for creating new sub-projects.

[rawlingsj]

Perhaps we should keep this RFC focussed on what our desired end state is and keep prioritisation a separate discussion? That would help understand what's involved and encourage community contributions if folks felt it important to them?

[squeedee]

The examples are a part of our e2e as well, we currently kill two birds with one stone and it's an efficiency I think we want to maintain.

[rawlingsj]

There's been some feedback that a community maintained set of examples that live on their own repo would aid contributions for wider integrations and scenarios. @vrabbi did you have some thoughts on this?

Once we add conventions and say Jenkins plus a growing number of other integrations it would be good if they existed in a separately maintained repo we can add more automation beyond the scope of the core cartographer repo.

[vrabbi]

I think that having an examples repo seperate is of huge value. I domt think e2e needs to be run against all examples so having core functionailty for testing in the main repo makes sense but by having an additional repo only for examples, it can server as a central location for examples of using different integrations like kaniko,jenkins,argo etc.

[vrabbi]

And having that under the cartographer umbrella is key i believe from a community perspective to show that cartographer truly is pluggable by design. If its in an official cartographer repo it gains more credability.

[squeedee]

This one resonates for me, hence the story I created. As a first step, this enables:

1. Treating the docs as an 'umbrella' site, supporting multiple products in the Cartographer group
2. Making it obvious that docs change at a different rate than any one repository, and not confusing people by being inside tagged versions of any given product.
3. Letting us skip unit, integration and e2e tests for our controllers when iterating on docs.

[cirocosta]

I'm particularly not a fan of having the website layout etc as part of the same codebase as the controllers themselves, but I do find useful the benefits that having documentation in the same repo as the code brings, like the ease of having PRs that update code also updating documentation (naturally, not a huge deal in case we do split it - as long as we ensure that we're always keeping the docs in sync etc).

more concretely:

1. I think it's great that if we change something meaningful in the architecture, that we'd have a change coming along in architecture.md which would fall under the same tag as the one where the code lands, etc
2. not great that we maintain in the same repo things like header.html

personally, I'd tend towards trying to keep content (plain markdown, like https://github.com/vmware-tanzu/carvel-ytt/tree/develop/docs) in this repo, but all the website structure etc in another if possible (e.g, see https://github.com/vmware-tanzu/carvel).

wdyt?

[squeedee]

I have seen no evidence that the docs move at the same pace as our controllers. We often need to work through a range of changes to make updates to most of the docs viable. The one place where doc's should be in lock step with changes, is changes to the API (Reference section). Hence my effort to make sure that API documentation is inline (pkg/api/.... doc comments). During the docs split, we'll need to rework the code that pulls in api docs into the Reference section (pretty easy) and make sure there is a process to ensure we run that before creating a new Doc Version tag for each controller.

[cirocosta]

at the moment, runnable is a controller that is ran as part of the same process that brings up the other core controllers (differently from the example given of Convention service) - if we were to split Runnable into its own repository, do you think we should then make it its own controller? My understanding is that yes, it should (given the use of the term "microservices" throughout the proposal).

[squeedee]

wouldn't we have to? I don't see a choice once it's extracted into another repo.

[scothis]

Would it also make sense to split ClusterSupplyChain/Workload from ClusterDelivery/Deliverable? These components are highly likely to be installed into distinct clusters.

[waciumawanjohi]

These components are highly likely to be installed into distinct clusters.

That is true. Do we have a reasonable expectation that users would object to installing both CRDs in a cluster only to leverage one? Would the value delivered match the work of separating the code? (As they do share code)

[squeedee]

Please see #571 (comment) wrt priorities for this work. I think ultimately it would be nice, but until we see driving factors as @waciumawanjohi suggests, it's not a need.

[rawlingsj]

I've certainly seen pushback from end users for installing build related components (including CRDs) into a target run cluster. Having a standalone / microservice installation for this makes sense to me.

[scothis]

Kubernetes is a curious case, as it is developed as a mono repo and consumed as component repos.

[rawlingsj]

yeah I guess I was trying to show that there's a wider kubernetes ecosystem that helped evolve the project. I.e specific areas developed special interest groups that iterate at their own cadence. That's quite a good model to help encourage wider efforts and involvement from others.

[davidmirror-ops]

A further discussion (probably for a separate RFC) would deal with how splitting into separate repos could trigger changes in Governance, introducing the idea of Working Groups/Feature areas (see Harbor as an example). With that approach we could define focus areas for maintainers and potentially onboard contributors for 'microteams' with a clear scope.