🧩 Pre-Commit Hooks Update: Commit Message Tags, Versioning & Team Workflow

[untoldengine]

Hey everyone 👋

I’ve made a small but meaningful update to our pre-commit hooks — and it’s going to make our workflow smoother for everyone. This update helps us keep commit messages consistent, automate version bumps, and ensure commits are tested before they land in main branches.

---

🚀 Why This Matters

This isn’t just about rules — it’s about collaboration and clarity. By following the same commit format, we make it easier to:

• Understand what changed (at a glance)
• Generate clean, automated changelogs
• Version the engine automatically based on real work (features, fixes, etc.)

---

🧩 What’s New

1️⃣ Commit Message Tags

Every commit message should start with a descriptive tag that summarizes the type of change:

• [Feature] — new feature
• [Patch] — small, safe fix
• [Bugfix] — fixing an issue
• [API Change] — breaking API update
• [Docs] — documentation update
• [Refactor] — internal code restructuring
• [Chores] — maintenance, cleanup, or tooling update
• [CI] — continuous integration or workflow change
• [Test] — adding or updating tests
• [Performance] — performance improvement
• [Security] — security fix

Examples:

• [Feature] Add real-time shadow rendering
• [Docs] Update installation guide with macOS setup

If the prefix is missing, the hook will show a friendly reminder with all valid tags.

---

🧠 How the Tags Are Used

These tags are more than labels — they’re used to drive versioning and changelog generation:

• [API Change] → major version bump
• [Feature] → minor version bump
• [Patch] or [Bugfix] → patch version bump

When a release is prepared, our scripts (for example, next-version.sh) and git-cliff automatically:

• Compute the next version (using the tags above)
• Group commits in CHANGELOG.md by their tag

This makes our releases clear, predictable, and automated — no manual version guessing!

---

🧪 Quick Tests Before Commit

The pre-commit hook also runs a fast, filtered test suite:

swift test --filter "UntoldEngineTests"

This keeps the engine stable without running the full test suite every time. If something fails, you’ll know before it reaches a PR.

---

⚙️ How to Enable Pre-Commit Locally

If you haven’t already, enable the hooks once after cloning:

brew install pre-commit
pre-commit install --hook-type pre-commit --hook-type commit-msg

(You can also use pip install pre-commit if you prefer Python.) After this, the hooks will automatically run before each commit.

---

🚧 If You Run Into Errors

Sometimes the hooks might fail because of local environment issues (for example, broken tests or setup). You can bypass them temporarily by adding the --no-verify flag:

git commit --no-verify -m "[Chores] Temporary commit skipping hooks"

Please use this sparingly. Skipping validation means your commit won’t be picked up by the automated versioning or changelog system.

---

🗂️ Summary

Feature	Description
Commit message tags	Keep commits clear and meaningful
Automated versioning	Uses tags to bump major/minor/patch
Changelog generation	Groups commits automatically by type
Pre-commit test	Runs UntoldEngineTests before committing
Bypass option	--no-verify (use sparingly)

---

💬 Let’s Collaborate

These changes are part of making our workflow more open and maintainable for everyone. If you have ideas for additional tags (for example [Style], [Deprecation], etc.) or run into any issues setting up pre-commit, please comment here.

Let’s keep refining this process together — small improvements like these make collaboration smoother and help us move faster as a team. 🚀