{"id":"l-git-4-3","courseId":"git-github","lang":"en","kind":"lesson","summary":"Write commit messages that explain why, follow the Conventional Commits format when a team uses it, mark versions with annotated tags, and publish a GitHub Release with generated notes.","html":"

Six months from now you’ll run git log on your portfolio looking for when the dark theme broke, and you’ll be reading messages written by past you. “updates”, “fix”, “asdf” won’t help. History is only as useful as the words attached to it. This lesson is about making those words count, and then about naming the moments that matter: versions.

\n

What a good commit message looks like

\n

A commit message has a subject line, a blank line, and an optional body:

\n
Text
Fix footer overlapping content on mobile\n\nThe footer used position: fixed, so on screens shorter than\nthe content it covered the last project card. Switch to a\nnormal flow footer and add bottom padding to the grid.\n\nCloses #13
\n

The conventions, and why they exist:

\n\n

Use git commit without -m when a change needs a body; your editor makes multi-line messages easy. For one-line changes, -m is fine.

\n

Conventional Commits

\n

Many teams adopt a structured format called Conventional Commits:

\n
Text
feat(projects): add tag filter to projects page\nfix(nav): close mobile menu when a link is clicked\ndocs: add setup steps to README\nci: run HTML check on pull requests\nfeat!: rename data-theme attribute to data-color-scheme
\n

The shape is type(optional scope): description. The specification defines feat (a new feature) and fix (a bug fix); teams commonly add docs, style (formatting only, not CSS), refactor, perf, test, build, ci and chore. A ! before the colon, or a BREAKING CHANGE: footer, marks a change that breaks existing users.

\n

The payoff is automation. Because the type is machine-readable, tools can generate changelogs and choose the next semantic version for you: fix bumps the patch number (1.4.2 to 1.4.3), feat the minor (1.5.0), a breaking change the major (2.0.0).

\n

Conventional Commits usually keeps the description lowercase, which differs from the capitalised style above. Neither is wrong. Use what the repository already uses; consistency beats preference. For your portfolio, try Conventional Commits; it’s common enough on teams that the habit pays off.

\n\n

Tags: naming a moment

\n

Branches move; tags don’t. A tag is a permanent name for one commit, used to mark versions: the portfolio as it was at launch, at v1.1, and so on.

\n

Git has two kinds. A lightweight tag is just a name pointing at a commit. An annotated tag is a full object with the tagger’s name, a date and a message. Use annotated tags for releases:

\n
Terminal
git tag -a v1.0.0 -m \"Portfolio launch\"\ngit tag                       # list tags\ngit show v1.0.0               # tag message, then the commit it points at\ngit tag -a v0.9.0 b2e04f3 -m \"Preview for mentors\"   # tag an older commit
\n

Tags stay on your machine until you push them, which surprises almost everyone the first time:

\n
Terminal
git push origin v1.0.0        # one tag\ngit push --follow-tags        # commits plus any annotated tags that point at them
\n

Treat a pushed tag as permanent. If you tagged the wrong commit and already pushed it, publish a new version (v1.0.1) rather than moving v1.0.0 under people who may have used it.

\n

GitHub Releases

\n

A release on GitHub is a tag plus a title, notes and optional downloadable files. Open your repository’s Releases page, choose Draft a new release, pick the tag (or create one), and click Generate release notes: GitHub lists the pull requests merged since the previous release, with their authors. Edit the notes into something a human wants to read, then publish.

\n

The CLI does the same in one line:

\n
Terminal
gh release create v1.0.0 --title \"Portfolio v1.0.0\" --generate-notes
\n

Good pull request titles become good release notes for free, one more reason the earlier habits pay off.

\n\n

Clean messages, tags and releases make history readable. The final step is making main trustworthy without having to watch it yourself: automated checks on every pull request, and rules that enforce them.

\n","toc":[{"id":"sec-1","text":"What a good commit message looks like","level":2},{"id":"sec-2","text":"Conventional Commits","level":2},{"id":"sec-3","text":"Tags: naming a moment","level":2},{"id":"sec-4","text":"GitHub Releases","level":2}],"takeaways":["A good subject line is short, imperative and specific (“Fix footer overlap on mobile”); the body, after a blank line, explains why.","Conventional Commits prefix the subject with a type such as feat, fix or docs, which lets tools derive version numbers and changelogs.","Annotated tags (git tag -a v1.0.0 -m "…") record who tagged what and when; they’re the right kind for releases.","git push doesn’t send tags; push them with git push origin v1.0.0 or git push --follow-tags.","A GitHub Release is a tag plus notes and optional files, and GitHub can generate the notes from merged pull requests."],"further":[{"title":"Git Basics, Tagging (Pro Git)","url":"https://git-scm.com/book/en/v2/Git-Basics-Tagging"},{"title":"Commit Guidelines (Pro Git)","url":"https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines"},{"title":"About releases","url":"https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases"},{"title":"Automatically generated release notes","url":"https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes"}],"quiz":[{"q":"

Which subject line best follows common Git conventions?

","options":[{"text":"Fixed some bugs.","why":"Past tense, a full stop, and “some bugs” tells a future reader nothing about what changed."},{"text":"Changes to the footer, nav, colours and the contact form so it works on phones now","why":"Far too long for a subject, and it lists four changes, which suggests four commits."},{"text":"WIP","why":"Fine as a temporary local commit you’ll squash, but meaningless once it’s in shared history."},{"text":"Fix footer overlapping content on mobile","why":"Correct. Imperative, specific, under 50 characters. It completes the sentence “If applied, this commit will…”."}],"answer":3},{"q":"

Under Conventional Commits and semantic versioning, which change should bump version 1.4.2 to 2.0.0?

","options":[{"text":"fix: correct contrast on dark mode links","why":"A fix maps to a patch release, 1.4.3."},{"text":"feat: add tag filter to projects page","why":"A new feature maps to a minor release, 1.5.0."},{"text":"feat!: rename the data-theme attribute to data-color-scheme","why":"Correct. The ! (or a BREAKING CHANGE: footer) marks a breaking change, which maps to a major release."},{"text":"docs: explain how to run the HTML check","why":"Documentation changes don’t affect the published behaviour and usually don’t trigger a release at all."}],"answer":2},{"q":"

You ran git tag -a v1.0.0 -m "Portfolio launch" and git push. The tag isn’t on GitHub. Why?

","options":[{"text":"git push doesn’t push tags by default; run git push origin v1.0.0 (or git push --follow-tags).","why":"Correct. Tags are pushed explicitly, so you don’t accidentally publish experimental ones."},{"text":"Annotated tags can’t be pushed; only lightweight tags can.","why":"Both kinds can be pushed. Annotated tags are the recommended kind for releases."},{"text":"GitHub only accepts tags created through its Releases page.","why":"GitHub accepts any pushed tag, and a release can be created from it afterwards."},{"text":"The tag name needs to start with release-.","why":"Tag names are free-form. v1.0.0 is the common convention."}],"answer":0},{"q":"

What’s the main advantage of an annotated tag over a lightweight tag for a release?

","options":[{"text":"Annotated tags can point at any commit; lightweight tags only at HEAD.","why":"Both kinds can point at any commit. Give the commit ID after the tag name."},{"text":"An annotated tag is a full object with tagger, date and message, so the release records who marked it and why.","why":"Correct. A lightweight tag is only a name for a commit, like a branch that never moves."},{"text":"Annotated tags move forward with new commits, like branches.","why":"Neither kind of tag moves. That’s the point of a tag."}],"answer":1}],"exercise":{"kind":"spot-bug","language":"text","code":"feat(projects): add tag filter to projects page\nfix: stop footer overlapping content on mobile\nUpdated stuff\ndocs: add setup steps to README\nfeat(contact): Added contact form, fixed nav and changed colors\nchore: update html-validate dev dependency\nfix(nav): close mobile menu when a link is clicked\nstyle projects grid spacing","bugLines":[3,5,8],"title":"Review the commit messages","prompt":"

These are the commit subjects on a pull request to your portfolio, a repository that follows Conventional Commits (type(optional scope): description, imperative, one change per commit). Select the three lines a reviewer should ask to be rewritten.

\n","hints":["Every subject needs a type followed by a colon.","Check the mood of the verbs, and count how many changes a single line describes.","In Conventional Commits, style means code formatting, not CSS work, and it still needs a colon."],"explanation":"

Line 3, Updated stuff, has no type and says nothing; something like refactor: rename nav classes to BEM would. Line 5 uses past tense and bundles three changes (contact form, nav, colours) into one commit; split it into feat(contact): add contact form, fix(nav): … and a separate commit for the colours, such as feat(theme): … (not style:, which is for formatting only). Line 8 is missing the colon, so tools can’t parse it, and style in Conventional Commits means formatting-only changes; spacing in the grid is a visible change, so fix(projects): tighten grid spacing on mobile fits better. The other lines are well-formed: type, optional scope, colon, and a specific imperative description.

\n","checkLabels":{}},"words":713,"readMinutes":3}