Issues, features, bugs, versions, releases
Beginner Core Git
Why this matters
Work in a development team is organized around issues, and shipped in releases. Git sits between the two: every branch, commit and merge request points back at an issue, and every release is a point in Git's history. Once you know the words, you can read a project's activity like a story.
From requirement to issue
Somebody wants something: a customer, a manager, a regulation, a colleague. That is a requirement. To become work, it is written down as an issue in the project's tracker: GitLab and GitHub both have issues built in; many companies use Jira, where the same thing is called a ticket.
Issues come in kinds, usually marked with labels:
| Kind | Meaning | Example at Northwind Trails |
|---|---|---|
| Feature | Something new that users will notice | #21 "Add a difficulty filter to the trail list" |
| Bug | Something that does not behave as intended | #15 "Trail list crashes when a distance is empty" |
| Hotfix | An urgent bug fix that goes to production immediately, outside the normal schedule | #23 "Wrong region name shown for Harbour Path" |
| Chore / task | Work users do not see: updating a library, cleaning up, documentation | #12 "Add Windows steps to the installation guide" |
The kind decides the branch name (feature/21-…, fix/15-…, hotfix/23-…, docs/12-… in the playground's CONTRIBUTING rules) and how urgently it travels through the environments.
From change to release
Once changes are merged, the team decides when to hand them to users. That is a release: a named version of the software.
The remaining words describe the machinery:
| Word | Meaning | Where you meet it |
|---|---|---|
| Pipeline | The automated sequence of steps that runs after every push: build, test, package, deploy | The green tick or red cross on a merge request |
| Artifact | A file produced by the pipeline: a build, a report, a package | The pipeline page, "Download artifacts" |
| Deployment | Putting a build into an environment | "Deployed to staging" on a merge request |
| Rollback | Deploying the previous version again because the new one misbehaves | An incident, and the sentence "we rolled back" |
| API | The rules by which one program talks to another over a network; developers say "the API changed" when the contract between two programs changed | Documentation you may be asked to write; version numbers where the first digit changes |
"Released" and "deployed" are different: a release is a named version; a deployment puts some version into some environment. Version 2.4.1 may be released (tagged, notes written) and deployed to staging, but not yet to production.
Reading the traces in Git
Once you know the vocabulary, a project's history reads easily:
d3f1a2b docs: add Windows steps to installation guide (#12)
9c7e4d0 fix: handle empty distance in trail list (#15)
b81f0aa Merge branch 'feature/21-difficulty-filter' into 'main'
5a0c9e1 chore: release 1.2.0Each line is a commit; the #12 and #15 point at issues; the merge line shows a feature branch arriving; the last line is the release commit that got the tag v1.2.0.
Common mistakes
- Working without an issue. A branch with no issue number is hard to review and impossible to trace later. Create the issue first, even for small documentation changes; it takes a minute.
- Reusing an issue number for different work. One issue, one branch, one merge request. Follow-ups get their own issue.
- Confusing "closed" with "released". Closing an issue means the change is merged. Users have it only after a release and a deployment.
- Writing release notes from memory. Read the merged merge requests since the last tag; that is the list.
Try it yourself
Goal: name a branch for a new issue by the team's rules.
- Open
CONTRIBUTING.mdin the playground and read the "Branches" section. - A new issue #33 is titled "FAQ: add a question about Windows". Decide its kind and write the branch name.
- Write the first line of the commit message that will finish it.
Expected result: a branch name of the form type/issue-short-title and a commit subject with a type prefix and the issue number.
Show solution
It is documentation work, so docs/33-faq-windows-question (any short, lowercase, hyphenated title is fine). Commit subject: docs: add Windows question to FAQ (#33). The number in both places lets GitLab link the branch and the commit to the issue automatically.