Splitting into individual repositories per-feature - good idea or not?

[jcbhmr]

the pro/con of this is mostly the same as monorepo vs polyrepo.

Here's some reading I did:

• https://monorepo.tools/
• https://blog.bitsrc.io/monorepo-vs-polyrepo-5-things-you-should-consider-897f3b588e70
• https://www.reddit.com/r/ExperiencedDevs/comments/12v3nfi/monorepo_vs_polyrepo/
• https://webo.digital/blog/monorepo-vs-polyrepo-architecture/
• https://github.com/joelparkerhenderson/monorepo-vs-polyrepo
• https://earthly.dev/blog/monorepo-vs-polyrepo/

Pros of this:

• It means you can use on: release in GitHub Actions without re-releasing the entire monorepo
• You can actually use GitHub Releases without releasing a bunch of unrelated other monorepo things
• Individuals can be granted full autonomy over an entire repository instead of meshing in a monorepo
• You can test things individually per-repo with per-repo GitHub Actions
• in github packages, the README that is shown won't be the monorepo readme, but the actual source repo readme
• each polyrepo can have its own "style" or whatever. some might be release-based (publish on release) others trunk-based (publish on push to main).
• each polyrepo can have its own GitHub Pages documentation sub-site and manages its own docs stuff

Cons of this:

• Need to publish each feature INDIVIDUALLY in a way that isn't immediately obvious (still in the spec text tho)
• Need to create MANY individual repositories instead of just one
• Need to MANAGE those repositories. that means issues, settings, etc.
• Need to duplicate a bunch of content across many repositories like a general readme template
• basically just MORE THINGS that are in MORE PLACES instead of all in one place

I think the killer argument pro-polyrepo is this: it makes it easier to isolate and delegate features to people to do their own way

But counter, the killer argument for monorepo: it's the way the @devcontainers org does it

Some preliminary findings from my experimentation:

• its relatively easy to use https://oras.land/docs/commands/oras_push to push a feature. no strings attached. you just push devcontainer-feature.json and install.sh in a tarball. https://containers.dev/implementors/features-distribution/#oci-registry

• its easy to publish oci packages from jcbhmr/features-cmake to jcbhmr/features/cmake with NO EXTRA TOKEN NEEDED just permissions: { packages: write }

• its easy enough to just search for owner:jcbhmr /features\\/.+/ package_type:container via REST API and get a list of feature packages

• its relatively easy to publish a feature index. its just a json file of all the feature manifests in a big list.

• I ASSUME that you need to store features under a /features/my-feature naming convention so that the /features index collection can use the "id" property of each of said features in said manifest to implicitly point to it when you use it? i don't think there's a "containerURI" or similar property of devcontainer-feature.json that allows ghcr.io/devcontainers/features to reference a feature ghcr.io/devcontainers/my-unscoped-feature i think it MUST BE ghcr.io/devcontainers/features/my-scoped-feature in order to be reference-able by the devcontainers/features index collection 👈 this is a thing to be AWARE OF

• its REALLY nice to have isolated feature repos so you can do your thing in one and test JUST THAT ONE FEATURE without needing complicated github actions tooling to isolate and test that single folder that changed. 👈 this is the biggest win i experienced; having per-repo github actions instead of wrangling "what folders changed?" is wayyyy easier imo

• its also nice to see the actual readme of the feature when browsing to that feature's package instead of the monorepo's readme. github packages doesn't seem to support subfolder package readmes

• doing things in each their own repo gives you a lot more control over testing methodology. I've adopted this script in my experiments: (below)

• you CAN DEFINITELY use features that aren't part of a collection. the collection is only there for metadata for https://containers.dev/features

#!/bin/bash
set -ex
[[ -n $1 ]] && image=$1 || image='mcr.microsoft.com/devcontainers/base:debian'
[[ -n $2 ]] && options=$2 || options='{}'
feature_dir=$PWD
temp_dir=$(mktemp -d)
trap 'rm -rf "$temp_dir"' SIGINT SIGTERM ERR EXIT
pushd "$temp_dir"
mkdir -p .devcontainer
cat <<EOF | tee .devcontainer/devcontainer.json
{
  "image": "$image",
  "features": {
    "./feature": $options
  }
}
EOF
rsync -av --exclude .git "$feature_dir/" "$PWD/.devcontainer/feature/"
tree -a
container_id=$(devcontainer up --workspace-folder . | jq -r .containerId)
devcontainer exec --workspace-folder . cmake --version
docker kill "$container_id"

[jcbhmr]

imo i like the polyrepo because:

1. the github actions flow is wayyy better per-repo than trying to mess with "what folders changed?" and then test only those.
2. scale-down the (perceived) burden of a contributor/maintainer to just a single feature instead of the massive monolith of all features.
3. its newfangled and cool and fancy and interesting