Idea: releases, changesets and upgrade paths

[owenversteeg]

So let's say Bob uses the starter and makes a site and then a month later Alice fixes a bug, or adds a feature, or some other change happens here in this repo. At that point, Bob probably has heavily modified the starter and he can abandon all hope of a clean Git add upstream/fetch/merge, he's probably going to have to manually pick stuff over by hand.

Of course some (many) of those things may not be things Bob wants or needs, so my thought is that it's probably best to have changes broken out individually. Commit-level is too granular and a pain, release-level is too broad, so I propose that each PR adds a simple one-line-of-text changeset that starts with (feature/bugfix/SECURITY/template) and a Github compare link with hashes in URL. Major project restructuring or extreme changes should be a new major release. As part of this, it'd be important that PRs with an important feature or bugfix come in one piece. Five (or ten, or thirty) commits in one PR is fine, but as soon as there are multiple PRs to fix one bug then things get a bit out of hand. This is good practice for other reasons though, so shouldn't be an issue.

I imagine most changes will be template, aka not important to merge for people that use the starter. Here's how I'd see this going:

(Date merged into main) (Type) (Change text) (Compare link)
March 15 2024 - Template - change wording on blog - [changes](https://github.com/CriticalMoments/CMSaasStarter/compare/ffd1a1d...5e831e1)
March 12 2024 - Template - modify homepage colors - [changes]
March 9 2024 - SECURITY - prevent API key leakage - [changes]
March 8 2024 - Template - increase footer padding - [changes]
March 4 2024 - Bugfix - prevent menu collapse on iOS 14 - [changes]

Probably the easiest is just a CHANGES.md that people manually update on each PR? There's this - https://github.com/apps/changeset-bot - but that's more complex and for monorepos.

Thoughts? This is probably the easiest way to let people "get" security and/or feature updates while not making things too complex.

[owenversteeg]

so it occurred to me that this may be a bit of a pain for small updates to the template (which probably 90% of commits will be) - so one idea is to not require a change comment for template type updates and only for security/bugfixes/feature additions?

[scosman]

Sounds like good best practices. We should also aim to squash merge PRs that have multiple commits that need to be taken as a whole or not at all.

Want to just start for security+bugfix issues? Features will be harder (sometimes across commits, and we want that history for maintainability, likely to have some integration work for forks anyways). Template changes seem un-necessary.

Want to kick off a template? New markdown file in root?

[owenversteeg]

Glad you agree!

The squash-merge for PRs is something I've waffled back and forth on for a while (on many projects.) These days I'm on the side of not squashing WHEN commits are well structured. First, and most importantly, you lose information by doing this. If you structure your commits well, you can provide information in the commit pattern and structure of changes. For example, let's say I implement a widget, and I do it in the most Svelte-y way, but that causes a bug, so my second commit is to alter my implementation. That pair of commits is helpful and demonstrates the thinking process, exact changes between the two methods et cetera. Or, I'm implementing a complex feature and I break it into several commits to demonstrate the expansion over time - I think this provides more information on the development of the feature versus just one squashed commit. That said, for a trivial change/typo-fix commits/obvious bugfix/forgetting to add changeset or whatnot then squash away obviously, not much in the way of information lost there. Can also ask committers to squash commits themselves when there is not much "information" in the changes.

I agree that template changes are unnecessary. Features... sure, will be less trivial, but I don't think it should be much work and I really do think the payoff is there. If someone sees a new feature here that they need, they're going to want it and this makes things a lot easier; we save them a bunch of time in exchange for writing a single line of text. Github has an easy comparison UI across multiple commits; just tack on your two hashes at the end such as https://github.com/CriticalMoments/CMSaasStarter/compare/ffd1a1d...5e831e1 and worst case, if some feature gets split up by a bugfix in the middle or whatnot, then it can be two or more entries in the changeset, that's not so bad. Besides, it's not like we're giving a guide on how to write it yourself - it's a date, a line of text and a link to a diff, just an entry point for implementing it yourself. Sure, it'll be some work to integrate those changes as people actually use the template and change things, but I think people will be very grateful when they need to use it (probably myself included, at some point!)

I'd be happy to start the template, yep CHANGESETS.md in root. I'm thinking the format I described above, plus either a hash or two hashes to diff. I'd also add a comment at the top describing the format of each line so it's easy for people to understand the file and add their changeset.