Tags, Releases, and Semantic Versioning
Objective. Students create lightweight and annotated Git tags, push tags to a remote, interpret semantic version numbers, and create a GitHub Release tied to an annotated tag.
This lesson, its worked examples and its practice questions has not yet been verified by an industry-certified professional or by a certification or approval body. It is a study draft and may contain errors. Do not use it as instructions for work on a job site or on live equipment. Always follow your instructor, your supervising professional, and current official references and regulations.
VoTechWorks program approval and accreditation are still in progress. Credentials are issued only by the certifying bodies named in each program, after their own exams.
What Are Git Tags?
A tag is a named pointer to a specific commit in your Git history. Unlike a branch, a tag does not move as new commits are added — it permanently marks a moment in your project's timeline. Tags are most commonly used to mark release points, such as version 1.0.0 of your application.
Git supports two kinds of tags: lightweight and annotated.
Lightweight Tags
A lightweight tag is simply a name that points directly to a commit. It stores no extra metadata. Create one with:
```bash
git tag v0.1
```
This tags whichever commit `HEAD` currently points to. Lightweight tags are convenient for private bookmarks or quick labels during development, but they carry no author information, date, or message of their own.
Annotated Tags
An annotated tag is stored as a full Git object. It records the tagger's name, email, date, and a message — making it the recommended choice for public releases. Create one with:
```bash
git tag -a v1.0.0 -m "First stable release"
```
The `-a` flag signals an annotated tag; `-m` supplies the message inline (omitting `-m` opens your default editor). You can inspect the tag object with `git show v1.0.0`, which displays the tag metadata followed by the commit it points to.
Pushing Tags to GitHub
By default, `git push` does not upload tags. You must push them explicitly:
```bash
git push origin --tags
```
This pushes every local tag that the remote does not yet have. To push a single tag, use `git push origin v1.0.0`. Once pushed, tags appear in the Tags section of your GitHub repository.
Semantic Versioning
Semantic versioning (SemVer) is a widely adopted convention for version numbers. The full specification is published at semver.org. A SemVer number takes the form:
```
MAJOR.MINOR.PATCH
```
| Component | Increment when… |
|-----------|----------------|
| MAJOR | You make a breaking, backward-incompatible change |
| MINOR | You add functionality in a backward-compatible way |
| PATCH | You make a backward-compatible bug fix |
Additional pre-release labels (e.g., `1.0.0-beta.1`) and build metadata (e.g., `1.0.0+20250101`) are also allowed under the spec.
Examples:
- Bug fix applied to `2.4.3` → `2.4.4`
- New feature added to `2.4.4` (no breaking changes) → `2.5.0` (PATCH resets to 0)
- Breaking API change applied to `2.5.0` → `3.0.0` (MINOR and PATCH both reset to 0)
Using SemVer in your Git tags communicates clearly to teammates, package managers, and CI/CD pipelines exactly what kind of change a release represents.
Creating a GitHub Release
A GitHub Release is a deployable snapshot of your software tied to a tag. It can include compiled binaries, source archives, and a human-readable changelog. To create one:
1. Navigate to your repository on GitHub.
2. Click Releases in the right sidebar, then Draft a new release.
3. In the Choose a tag dropdown, select your annotated tag (e.g., `v1.0.0`). If it does not appear, verify you have pushed it.
4. Give the release a title (commonly the version number).
5. Write a changelog-style description — list what was added, changed, fixed, or removed. Use plain language; bullet points work well.
6. Click Publish release.
The published release gets a permanent URL you can share with users or reference in documentation. Record this URL in your lab log for sign-off.
Safety and Professional Practices
- Never delete or rewrite a tag that has been pushed and shared. Other developers and automated systems may depend on it. If you tag the wrong commit, create a corrected tag (e.g., `v1.0.1`) rather than force-pushing over the old one.
- Protect your GitHub credentials. Never paste Personal Access Tokens or SSH private keys into a shared terminal, screenshot, or chat message. Use environment variables or a credential manager.
- Verify before pushing. Run `git log --oneline` and `git tag -l` to confirm you are tagging the intended commit before pushing tags to a shared remote.
- Keep your lab log entries accurate. Recording the correct release URL and tag names is part of professional documentation practice expected in the industry.
Key terms8
Materials: Git workstation, GitHub account, terminal, semantic versioning reference (semver.org), lab log
Check: GitHub repository shows at least two tags (one lightweight, one annotated) and a published GitHub Release with a readable changelog; lab log entry signed off; scenario quiz score 80% or higher.
Practice check8
Answer each question, then check it. Nothing is recorded; this is your own practice.
