Change Logs

By Amr

Estimated reading time: 2 minutes

Edit on Github

Aye aye, knowledge crusader! You’ve survived the trials of Pull Request Prose and the sacred rites of Atomic Commits. Now, it’s time to master the Arcane Arts of Documentation & the Grand Book of CHANGELOGS.


📖 Chapter 3: Changelogs & Documentation – The Chronicles of Code

What good is a spell if no one knows what it does? What use is a potion without a label? In this chapter, we etch our work into the annals of time with mighty tomes known as CHANGELOG.md and whispered runes called documentation.


📜 The Great Tome: 

CHANGELOG.md

The changelog is your codebase’s storybook. It should be clear enough for a newcomer, specific enough for a dev, and honest enough to admit when something broke.

🧾 Changelog Format (The Spellbook Edition)

## [1.2.0] - 2025-04-18
### Added
- OAuth login for wizards and mortals alike (#78)

### Fixed
- Session bug when users log in from enchanted forests (#123)

💡 Pro Tip: Use semantic versioning:

MAJOR.MINOR.PATCH = breaking.features.fixes.


🛠️ Automating the Tome (So You Don’t Forget)

Let the machines do the documenting when you’re busy summoning dark mode.

🧙 Tools of Automation:

  • Release Drafter (GitHub Action): Auto-updates changelog drafts from PRs.

  • Conventional Changelog: Parses commit messages and builds changelogs.

  • Semantic Release: Fully automates versioning + changelog + release.

Magical Setup (GitHub Actions + Release Drafter):

  1. Install the GitHub Action

  2. Create a release-drafter.yml config file

  3. Watch as your changelog updates itself after each merged PR


📚 Documentation Spells

If your codebase were a magical artifact, your docs would be the user manual etched on the side.

Types of Docs:

  • README.md: The welcome mat to your wizard tower.

  • CONTRIBUTING.md: The rules of the guild.

  • Wiki or Internal Docs: Detailed spell formulas (architecture, flows, edge cases).

  • Inline Comments: Only where your code speaks in riddles.


🧙‍♀️ Enchanted Best Practices

  • Document why, not just what.

  • Keep the changelog and README in sync with releases.

  • Don’t write novels. Be brief, be clear, be helpful.


🧠 Wizard Wisdom

“Code is for machines. Docs are for humans. And humans need help.


So there you have it—your story, your spells, your saga, all documented for the ages. You’re now the official historian of your repo realm. 🏛️

Ready to step into the high tower of Automation & GitHub Actions next? The machines await your command. ⚙️✨ Shall we conjure Chapter 4?