Laravel Git Blog - Releases

Conventional Commits for a Small Team

Wed, 21 Oct 2026 00:00:00 GMT

Six months of commit messages that say "fix", "wip" and "changes" tell the next developer nothing - and on a small team the next developer is usually you. Conventional Commits add one prefix to every message and turn the log into something you can actually read.

The whole format

type(scope): short summary

The types that earn their keep on a Laravel app:

feat - new behaviour (feat(billing): add invoice PDF download)
fix - a bug (fix(queue): stop retrying permanently failed jobs)
refactor - same behaviour, different code
test - tests only
chore - dependencies, config, tooling
docs - the README and friends

The scope is optional but cheap: one word naming the part of the app (billing, queue, auth). The summary stays imperative and under about 70 characters.

What it buys

git log --oneline becomes a changelog draft: everything user-visible is a feat or fix, everything else filters out. That is exactly the input the tags-to-changelog habit needs, and it makes releases a paste-and-edit job instead of an archaeology dig. Review gets faster too - a refactor prefix sets expectations before the diff loads, and nobody hunts for behaviour changes in a commit that announced there are none.

Breaking changes get a ! (feat(api)!: drop v1 endpoints) or a BREAKING CHANGE: footer, so they are impossible to miss at release time.

Adopt it without a fight

The failure mode is process, not spelling: a team that gets a 12-type spec and a CI gate on day one starts writing chore: stuff to make the check pass. Start smaller:

Five or six types, written in the README or pull request template.
Scope optional, body only when the why is not obvious from the diff.
No CI enforcement at first. Squash-merge pull requests and write the conventional message on the squash commit - main stays clean even when the branch's own commits are messy.

If it still feels like overhead after a month, drop it. A convention the team half-follows is worse than none, because it teaches people the log cannot be trusted. The bar is not a perfect history; it is a git log you can skim before a release and believe.

Keeping a Changelog From Git Tags

Wed, 21 Oct 2026 00:00:00 GMT

A changelog is only painful when you write it three months late. If you tag releases, most of the work is already done.

Tag what you ship

git tag -a v1.3.0 -m "v1.3.0"
git push origin v1.3.0

Annotated tags carry a message and a date, and they give you a name for "what is in production right now".

The log between tags is your draft

git log v1.2.0..v1.3.0 --oneline --no-merges

That list, cleaned up, is the release note. Short, descriptive commit subjects pay off here — another reason the commit-msg habit matters.

Keep a CHANGELOG.md in the repo

Add a section per tag, newest at the top, dated. Users of your package or app read it before upgrading; future-you reads it when something breaks and the question is "since when". For a Laravel app, note the migrations and any .env keys a release adds, because those are the steps a deploy can trip on.

The habit that makes it work

Write the entry at tag time, while the diff is fresh. A changelog maintained per release is ten lines of work; reconstructed quarterly it is an afternoon of archaeology.

Release Notes People Actually Read

Wed, 21 Oct 2026 00:00:00 GMT

Two artifacts get confused constantly. The changelog answers "what changed, exactly" for developers - keep a changelog from git tags covers generating one honestly. Release notes answer a different question for a different reader: "what can I do now that I could not before, and did anything I rely on change?" Users, not maintainers. The mistake is shipping the ledger to the letter's audience.

Lead with what the reader gets

Not "Fixed bug in invoice retry logic" but "Failed invoice payments now retry automatically - no more manual re-runs." Same change, different subject. The test for each line: can a user tell whether to care in five seconds? If the change is invisible to them - refactors, dependency bumps, internal cleanup - it does not belong in release notes at all. It belongs in the changelog, which is exactly why having both frees you.

The shape that works

Three groups, in this order, skipping any that are empty:

New - capabilities, with a sentence on when you would reach for each.
Improved and fixed - changes to things people already use, phrased from their side ("exports are faster", not "optimized query").
Breaking and action needed - the section everyone reads first even though it is last. Anything requiring a config change, a migration, or a new minimum version goes here, with the exact step to take. Hiding a breaking change in the fixed list is how release notes lose trust permanently.

The habits behind good notes

Write the note with the PR, not at release time. One line in the pull request description - "release note: ..." - while the context is fresh beats reconstructing twenty changes from commit messages on release day. Your PR template can carry the prompt.

Tie notes to the tag. Notes ship when the version ships - see deploy with tags, not branches - so "what is in production" and "what do the notes say" can never drift.

Keep a human pass. Generated drafts are a fine start; a generated final is a ledger wearing the letter's clothes. Ten minutes of editing per release is the whole cost.

Users who trust your release notes read them. That trust is built line by line, and spent in one "everything changed, nothing says why."

Deploying a Laravel App With Git Push

Mon, 19 Oct 2026 00:00:00 GMT

Self-hosting your git and your app on the same box has a nice property: a push can be the deploy. You need a bare repository and one hook.

The bare repo

git init --bare /srv/git/myapp.git

Add it as a remote on your laptop and push a branch you deploy from, for example main.

The post-receive hook

/srv/git/myapp.git/hooks/post-receive, made executable:

#!/bin/bash
set -e
APP=/var/www/myapp
git --work-tree=$APP --git-dir=/srv/git/myapp.git checkout -f main
cd $APP
composer install --no-dev --optimize-autoloader
php artisan migrate --force
php artisan config:cache
php artisan route:cache
php artisan view:cache

checkout -f syncs the working tree to the pushed commit. The artisan steps are the boring, repeatable part of every Laravel release.

Keep it honest

Run the hook as a user that owns /var/www/myapp but cannot sudo.
migrate --force runs unattended, so only push migrations you have tested against a copy of production data.
If the hook fails, the push still lands in the repo; redeploy by pushing an empty commit or rerunning the hook on the server.

This is one step above "SSH in and pull". When you outgrow it — zero-downtime releases, rollbacks, multiple servers — that is the point where a real pipeline earns its keep, not before.

Shipping a Laravel App From Git

Thu, 15 Oct 2026 00:00:00 GMT

A Laravel deploy is mostly the same few steps each time.

Build from a known commit

Deploy a tag or a commit hash, not whatever is on a branch right now.

Run migrations deliberately

Run them as a step you can see, and know how to roll back.

Warm the caches

Config, route and view caches are part of the release, not an afterthought.