How I shipped my first GitHub release (and what I learned)

My journey with Git

Software development and I have never really been the best of friends — which is exactly why I avoided going too deep into it for a long time. But as I work towards becoming a junior IT specialist, I’ve been forcing myself to properly learn Git instead of just memorising enough commands to survive.

Following the

I had two goals with this project.

First, sharpen my Python and CLI skills on something more interesting than another to-do app.

Second — and I’ll let you in on a secret — I eventually want to reverse engineer a Wordle cracker from the game’s core logic. But that’s a story for another post.

For now it’s terminal-only, though I’d love to eventually port it into something more visual. Today’s goal was simpler:

Ship it properly.

What I didn’t know before today

Turns out there’s a lot more to releases than just pushing code to GitHub and calling it a day.

Here’s what genuinely surprised me:

• Tags are not branches — they’re permanent references to a specific commit


• There are two types of tags:
  
  
  
  
  • lightweight tags (basically just a named pointer)
  
  
  • annotated tags (full Git objects containing metadata, author, date, and messages)
  
  
  
  
  
  



• GitHub Releases are built on top of tags, not the other way around



• Release notes and READMEs serve completely different purposes:
  
  
  
  
  • README = evergreen project documentation
  
  
  • Release notes = what changed in this version specifically
  
  
  
  
  
  

That last point especially changed how I think about documenting projects.

The process I followed

1. Create a meaningful annotated tag

git tag -a v1.0.0 -m "Terminal Wordle in Python — 6-guess game with colour-coded feedback and custom word list support"

I quickly realised "stable release" is a terrible tag message.

Tag annotations show up in:

• git show


• git log


• GitHub’s tag UI

So the message should actually explain what shipped.

2. Push the tag explicitly

git push origin v1.0.0

This caught me off guard the first time.

Tags don’t automatically push with a normal git push. You either:

• push them individually


• or use git push --tags
  

Tiny detail, but one that confused me immediately.

3. Build the release page properly

Instead of treating the release like an afterthought, I wrote:

• actual release notes


• a summary of what shipped


• a “What’s Next” section

I wanted someone landing on the repo to immediately understand:

1. what the project does


2. what changed


3. whether the project is still active

4. Create the wiki

I also built a small wiki containing:

• Home


• How to Play


• Custom Word Lists


• Changelog


• Roadmap

Keeping longer-form documentation inside the wiki made the repo itself feel way cleaner.

What I’d do differently next time

A few things became obvious almost immediately:

• 
  

  Start at v0.1.0, not v1.0.0

  
  
  
  
  
  • 
    v1.0.0 implies a level of stability I probably wasn’t ready to promise on a 9-commit repo
  
  
  
  
  
  



• 
  
  

  Use conventional commits from day one

  
  
  
  
  
  • feat:
  
  
  • fix:
  
  
  • chore:
  
  
  • etc.
  
  
  
  
  
  

This becomes especially useful once GitHub starts auto-generating release notes.

• Set up CI before the first release
  
  
  
  
  • even a tiny “does this run?” workflow is infinitely better than nothing
  
  
  
  
  
  

Try it yourself

If you’d like to try the project, feel free to clone it and mess around with it.

Any support is massively appreciated:

• stars


• forks


• issues


• feedback


• all of it ⭐

What’s next

• 
  

  v1.0.1

  
  
  
  
  
  • fixing a bug I spotted in my own word list (STRIN is apparently not a real word)
  
  
  
  
  
  



• 
  
  

  v1.1.0

  
  
  
  
  
  • ANSI colour output so feedback becomes green/yellow/grey instead of symbols
  
  
  
  
  
  

Full roadmap:

→

Thank you!

If you made it this far, genuinely thank you.

This is one of my first technical posts, and honestly just writing it helped me consolidate everything I learned today. If it helps even one person understand Git releases a little better, that’s already a win to me.

If you’re also learning Git from scratch:

you’re not alone — we’re all figuring it out one release at a time.

f40 ── .✦