Make the repo into a template

[johngallagher]

Hello! I'm loving this idea - thanks for putting it together!

One small suggestion - might it be worth turning this into a template?

I'd rather not clone down the whole project - I'd rather it create a project for me, based on this repo.

I think it's fairly easy to do this in the GitHub admin interface.

https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository

Hopefully that makes sense!

[tapegram]

@johngallagher Hello, and thanks for the feedback!

Doing a template is interesting, though I wanted to talk through some tradeoffs. Specifically, if the repository is a template, is that similar to forking, where you eventually can't easily get upstream changes?

I imagine that we do want people to be able to use this as a starting point and then evolve it based on their own personal needs, but also, there are probably projects that want to be up to date with the current version of monorail.

I haven't made many template repositories, so do you know how well it would handle both of these cases?

I will also do some reading about it in the mean time!

[johngallagher]

@tapegram thanks for the response! I don't know off the top of my head but I asked our robot friend and here's what it said:

Good question — the choice has real implications for how users interact with your starter and how you maintain it. Here's the core tradeoff:

Template Repositories

Advantages:

• Creates a completely independent repository with no Git history from the original — clean slate
• No upstream relationship, so users won't accidentally PR back to your template
• GitHub provides a prominent "Use this template" button, making the UX very clear
• Users get their own repo immediately without the "forked from" badge
• Works well for true "starting points" where you don't expect users to pull future updates

Disadvantages:

• No mechanism to pull upstream changes — once they've used the template, they're on their own
• If you fix a bug or improve the scaffold, users have to manually cherry-pick or diff
• Can't contribute improvements back easily (no common ancestor)

Forkable Repository

Advantages:

• Users can git pull upstream main to get your updates, security patches, framework upgrades
• Maintains Git history, which can be valuable for understanding why decisions were made
• Easy to contribute back via PRs if someone improves on your patterns
• Better for "living frameworks" that evolve over time

Disadvantages:

• Fork relationship is visible and permanent — some users find this awkward for "their" project
• Merge conflicts when pulling upstream if they've diverged significantly
• Users might accidentally target your repo with PRs
• Only one fork per user per GitHub account (without workarounds)

The Decision Heuristic

Use a template when it's truly a scaffold — users take it, customise heavily, and never look back. Think: create-react-app eject, cookiecutter projects.

Use forks when you're providing an opinionated framework or boilerplate that you actively maintain and users benefit from staying in sync. Think: framework starter kits with ongoing security updates.

For observability-focused starter repos specifically, I'd lean toward template if it's teaching patterns they'll adapt, or fork if you're shipping instrumentation config they should keep updated as OpenTelemetry SDKs evolve.

Doesn't look like there's a good option to me, but I wonder if you could offer both options somehow, with their own use case and tradeoffs.