The developer workflow end to end

Why this matters

Every question you will ask about a change ("is it done?", "can I test it?", "why can't customers see it?") is a question about where it is on this path. Developers carry the map in their heads; this lesson draws it. Later sections zoom into each part; here you get the whole route once, in order.

The path of a change

1. Requirement. Someone needs something. A customer, a support ticket, a manager, a regulation. Nothing in Git yet.
2. Issue. The need is written down as issue #12 in GitLab, GitHub or Jira: title, description, who will do it. From now on the number follows the work everywhere (lesson 1.6).
3. Branch. The person doing the work creates a branch from the latest main, named after the issue: git switch -c docs/12-windows-install-steps. The branch is a private lane: nothing done on it affects anyone else until it is merged (Section 6).
4. Change. Files are edited in the editor or IDE: a paragraph in docs/getting-started.md, a line in src/trailguide.py. This is the only step that is not about Git at all.
5. Test locally. Run the program, run the tests, preview the Markdown. Cheap checks before anyone else spends time.
6. Commit. The change is recorded as a snapshot with a message: git add, then git commit -m "docs: add Windows steps to installation guide (#12)". Several commits per branch are normal (Section 5).
7. Push. The branch is uploaded to the remote: git push -u origin docs/12-windows-install-steps. Now the team, and the pipeline, can see it (Section 7).
8. Merge request (GitLab) or pull request (GitHub). A page that says "please merge my branch into main", with a description, the diff, and a place to discuss. Opening it is a button on the platform (lesson 9.7, lesson 10.7).
9. CI pipeline. The platform runs the automated checks on the branch: tests, linters, a build. Green means the machine found nothing; red means stop and read the log (Section 14).
10. Review. One or more colleagues read the change, comment on lines, suggest edits, ask questions (lesson 13.7).
11. Requested changes. If the reviewer wants something different, the author goes back to step 4: change, commit, push. The merge request updates itself; the pipeline runs again. This loop can happen several times and is normal, not a failure.
12. Approval. The reviewer marks the change as good. Many teams require one or two approvals and a green pipeline before the merge button becomes available.
13. Merge. The branch's commits become part of main. The issue closes automatically if the description said Closes #12. The branch is usually deleted.
14. Deployment. The pipeline (or a person) deploys the new main to staging, then to production. Only now can users see the change (lesson 1.5).

Where each step happens

The loop between steps 4 and 11 is where you will spend most of your Git life: edit, commit, push, read the review, repeat.

What the workflow protects against

• Overwriting each other's work. Branches keep changes separate until they are ready.
• Breaking production. Tests and review happen before the merge; deployments happen after.
• Untraceable changes. Every line in main came through a merge request that links to an issue and to a reviewer's approval. When something goes wrong a year later, git log and the merge request tell the story.
• Work getting lost. Pushed commits live on the server; a broken laptop costs at most the unpushed part.

Do and don't

Common mistakes

• Editing on main by accident. Discovered at commit time, when git status says On branch main. Recovery in lesson 12.7; prevention: git status first.
• Forgetting to push. The merge request cannot see commits that exist only on your computer. "Your branch is ahead of 'origin/…' by 2 commits" in git status means push.
• Assuming "approved" means "done". Someone still has to press Merge, and something still has to deploy.
• Closing the issue by hand before the merge, or leaving it open after. Closes #12 in the merge request description does it at the right moment.

Try it yourself

Goal: map the team's merge request checklist to the steps of the workflow.

1. Open CONTRIBUTING.md in the playground and read the five items under "Merge requests".
2. For each item, name the step (1–14) it checks.

Expected result: every item corresponds to one of steps 3, 5, 8, 9 or 10.

Show solution

"Up to date with main" → step 3 (branch from latest, or update it). "Pipeline is green" → step 9. "Description says what and why, links the issue" → step 8 (and step 2 for the link). "Documentation updated" → step 4 and 5. "Reviewed your own diff" → step 10, done by yourself first.

Check yourself

1. A reviewer requested changes on your merge request. What happens next?

The merge request is closed and you open a new one The reviewer edits your branch You change the files, commit, push; the same merge request updates and the pipeline runs again

2. Which step makes your work visible to colleagues for the first time?

Commit Push Merge

3. The merge request was approved and merged an hour ago. Where is the change now?

In main on the remote, and in whichever environments have been deployed since On the customer's screen for sure Still on the author's branch only

Check answers