This website you are on has gone through multiple iterations over the years. At first, it was a stock Wordpress site (I was into minions back then) because that was the fastest way to get my thoughts on a URL. Bare bones, hardly any customization.

Then, I worked on a theme and got the taxonomy to a better place. Thanks to Wayback machine for storing copies of some portions of it. I wish I had done a better job of retaining some of my older work.

1. viii.in
2. vinayraghu.com

Later, when I got into Javascript, I rebuilt the whole thing as a singe page Ember application.

And currently, it is a Static site built via Gatsby.

Drafts

These are just the versions I shipped. Outside of that there are several failed redesigns, refactors and ground-up rewrites. I recently wrote about how incremental changes are much better than full blown refactors precisely for this reason. I think my problem is I love learning new technology and rebuilding my website is a familiar problem that I can recreate in different stacks as a learning exercise.

When the desire to redesign is combined with a desire to learn a new technology and actually push new features, there’s way too much scope in that ambition.

I listen to shop talk show regularly and one of the ideas that comes up from Dave Rupert is the idea of “Elon musk big bucks” token. For every project, you have one or two tokens where you can try something new but everything else remains simple or familiar. This way you’re still productive while learning one or two new things. As opposed to wanting to:

1. Redesign the site
2. Use tailwind
3. Publish a design system and tokens
4. Move to Next JS
5. Consolidate routes…

You get the idea.

Changelog

That brings me to the idea of a changelog. I love it because I want to chronicle my website and see how it has changed over the years. This actually is a little restrictive as I cannot throw away pieces that hold me back like the folder structure of how my blog posts are stored in the file system. But this is what will ensure I can go back in time and see pieces of the website over the years.

Here’s a link to my changelog. This is done mainly to chronicle the big changes to my site over time. I want to be able to publish a set of changes and look back at how the site evolved over time. I feel like there’s renewed focus back on personal blogs after we all took a hiatus and ported everything over to blogging platforms that eventually died or ruined their UX to increase signups and becoming walled gardens. I feel like now is a great time to own and be active on a personal developer blog. It's open, mostly free and you get to keep your content for perpetuity.

More importantly, I want to be able to record all changes done over time for my own amusement.

Along with keeping a changelog, I think it’s important to customize it in a way that makes sense for your project. This isn’t software that is sold or collaborated on by other people, so its a lot simpler and different from your typical changelog.

My Changelog rules

Unreleased changes

I find that maintaining a set of unreleased features does not work for me. I keep shifting priorities based on the day and what happens in that day so I can’t commit to a specific feature. Just that I’ll keep pushing changes.

What’s considered a change

A change can be a blog post or a bug fix or a UI tweak. I’ll write a whole post about my process but I think this was a missing piece for me because I considered only publishing a blog posts as success and that kept me from working on features I really liked, for example the tags page.

Semantic versioning

I want to be able to point to exact tags on github that correlate with a change but I also want to only cut a new version when I feel like there’s enough changes in there that warrants a version bump. This is why I don’t automate or cut a new patch for every commit. I’d rather chunk a meaningful group of changes together than simply bump the numbers up.

Automation

Changelog is generated automatically but version bumps are manual. I prefer it this way until I find it cumbersome, this will have to do.

Template

I don’t want to publish hashes to my commits or pull request links as these are all hosted on a private repository (by design). So the template is actually a lot simpler.

Commit linting

I like the freedom of being able to put anything in my commit messages. If this were a project with multiple people involved, I would enforce linting on commits.

Work in progress

All that being said, the whole thing is work in progress. I am hoping the entire site is perpetually on v1 and evolves over time.

Rollback

I haven’t had the need to do this but the idea with versioning for me is to be able to identify new issues and go back in time and find out the last working version. That way, it’s easier to see where the breakage was introduced. This site is not your typical distributed software so the concerns are far fewer about breaking changes and deprecations. Being able to find a good version to rollback to real quick gives me a lot of peace of mind.

What's the takeaway?

1. Maintain a changelog so you can see how your website has evolved over time
2. Refuse the temptation to start a ground-up rewrite and focus on incremental changes
3. Format your changelog so it makes sense to you
4. Tagging with semantic versioning helps a lot in pointing out exact versions of code with their associated changes so you can rollback to “last working version”.
5. This website has been through a lot 😀