Git Tag Reference
Semantic versioning with git tags for EBRAINS projects.
Tag Format
Semantic Versioning
| Version Component | When to Increment | Example |
|---|---|---|
| MAJOR | Breaking changes (incompatible API changes) | v1.0.0 → v2.0.0 |
| MINOR | New features (backward compatible) | v1.0.0 → v1.1.0 |
| PATCH | Bug fixes (backward compatible) | v1.0.0 → v1.0.1 |
Creating Tags
Simple Tag (Lightweight)
Annotated Tag (Recommended)
Annotated Tag with Detailed Message
Tag Specific Commit
Version Examples
Release Tags
Pre-Release Tags
| Label | Stability | Example | Usage |
|---|---|---|---|
| alpha | Very low | v2.0.0-alpha.1 | Early testing, unstable |
| beta | Medium | v2.0.0-beta.1 | Feature complete, testing |
| rc | High | v2.0.0-rc.1 | Release candidate, final testing |
Managing Tags
List Tags
Push Tags
Delete Tags
Checkout Tag
Version Progression Examples
Patch Release (Bug Fix)
Minor Release (New Feature)
Major Release (Breaking Change)
Version Decision Matrix
| Change Type | Example | Version Bump |
|---|---|---|
| Fix a bug | Fixed crash on empty input | 1.2.3 → 1.2.4 |
| Add optional parameter | New optional limit param | 1.2.3 → 1.3.0 |
| Add new endpoint | POST /api/export | 1.2.3 → 1.3.0 |
| Remove endpoint | Deleted /api/old | 1.2.3 → 2.0.0 |
| Change required field type | age from string to number | 1.2.3 → 2.0.0 |
| Rename function | getUserData → getUser | 1.2.3 → 2.0.0 |
| Add new response field | Added createdAt field | 1.2.3 → 1.3.0 |
| Change response structure | New error format | 1.2.3 → 2.0.0 |
| Deprecate (not remove) | Mark oldMethod deprecated | 1.2.3 → 1.3.0 |
| Security patch | Fix SQL injection | 1.2.3 → 1.2.4 |
Pre-Release Version Ordering
NPM Version Commands
For Node.js projects, use npm to bump versions:
These commands automatically:
- Update package.json version
- Create a git commit
- Create a git tag
Best Practices
Do
- Use the
vprefix for Git tags (e.g.,v1.0.0) - Create annotated tags (not lightweight tags)
- Write meaningful tag messages
- Follow semantic versioning strictly
- Document breaking changes clearly
- Update CHANGELOG.md before tagging
Don’t
- Don’t tag without updating version in package.json/files
- Don’t reuse or change existing tags
- Don’t skip versions (e.g., don’t jump from 1.0.0 to 1.2.0)
- Don’t use tag names without semantic meaning
- Don’t forget to push tags after creating them
Related Documentation
- Version Your Project Tutorial - Complete versioning guide
- Tagging Strategy - EBRAINS tagging conventions
- Release Management - Release process
- Semantic Versioning - Official specification
- Git Tagging - Git documentation