Agile in one page
Beginner Core Git
Why this matters
Most development teams organize work in short cycles and track it on a board. The board is where product people, testers and writers meet the developers, and every column on it corresponds to a state in the Git workflow. This page gives you the vocabulary; the rest is your team's flavour.
The pieces
| Term | Meaning | Where you see it |
|---|---|---|
| Backlog | The ordered list of everything the team might do: issues not yet scheduled | An issue list sorted by priority |
| Sprint / iteration | A fixed period (often two weeks) with a chosen set of issues | Milestones or iterations in GitLab, milestones or project views in GitHub |
| Board | Issues as cards in columns that represent states | GitLab issue boards, GitHub Projects |
| Label | A coloured tag on an issue: kind (bug, docs), area (api), priority (P1) |
Filters everywhere; some teams drive board columns with labels |
| Milestone | A goal with a date, usually a release: v1.2.0 |
Progress bar of closed vs open issues |
| Assignee | The person doing the work | On the card |
| Definition of done (DoD) | The team's checklist for calling an issue finished | CONTRIBUTING files, merge request templates |
| Stand-up | A short daily meeting: what I did, what I will do, what blocks me | Your calendar |
| Retrospective | A meeting at the end of a sprint about how the work went | Also your calendar |
The board, column by column
A typical board and what each column means for Git:
| Column | State | Git |
|---|---|---|
| To do | Chosen for this sprint, not started | No branch yet |
| Doing / In progress | Someone is working on it | A branch exists, commits accumulate, pushed regularly |
| In review | A merge request is open and waiting for review or changes | The review loop of the workflow |
| Done | Merged, and the definition of done is met | Commits are in main; the issue is closed |
Some teams add Testing (deployed to a test environment, QA verifying) between review and done, or Blocked for issues waiting on something. Cards move when the underlying Git event happens: opening a merge request moves the card to review, merging moves it to done, often automatically.
What this means for you
- Documentation is work on the board too. Create an issue for each documentation change and move its card like everyone else; it makes your work visible and reviewable.
- Labels are how you find things.
documentationordocslabels give you your own filtered view of the backlog;good first issuemarks tasks suitable for newcomers. - Milestones tell you what a release contains. Release notes are the closed issues of the milestone, in prose.
- "Done" is the team's definition, not yours. Read the CONTRIBUTING file or the merge request template before you declare a change finished.
Common mistakes
- Moving the card by hand while the branch is not pushed. The board should reflect reality; "In review" without a merge request confuses everyone.
- One issue for a whole sprint of documentation. Split it: one issue per guide or per change, each with its own branch and merge request. Small changes get reviewed; big ones wait.
- Ignoring milestones. If your change must be in a release, put the issue in that milestone, or it may be scheduled after.
Try it yourself
Goal: write a definition of done for a documentation change in the playground.
- Read the "Merge requests" checklist in
CONTRIBUTING.md. - Write, in three to five lines, what must be true before a documentation issue is "Done" in this project.
Expected result: a checklist that mentions review, the pipeline, linking the issue and the merge itself.
Show solution
One reasonable version: branch up to date with main; Markdown lint job green; merge request describes what and why and says Closes #NN; a maintainer approved; merged and the branch deleted; the page renders correctly on the docs site. Anything beyond the CONTRIBUTING list is the team's choice.