This lesson explains how we work on projects at makandra: how requirements become issues, how issues move through review and merge, and how changes reach production.
Important
Work on this lesson in
advisormode.
Learning goals
- You can explain why we have a development process and which outcomes it optimizes for.
- You can explain what an issue is, how it moves through its lifecycle, and how to cut a requirement into issues that are neither too small nor too large.
- You can write an issue that a colleague can implement without asking back.
- You can explain our gatekeeping: feature branches, code review, and squashed commits that keep history traceable with
git blame. - You use our merge request checklist on every merge request.
- You can explain how a change gets from a merged branch to production.
- You can work in Linear: configure a team's workflow, find your issues, move them through their states, and link your commits to them.
- You can describe Scrum, waterfall and lightweight Kanban-style processes in outline and say how they differ from our process.
Our process
Learn about our process. The squares represent the state of the issue in Linear:
In particular you should understand:
- Why do we have a process?
- What is an issue (formerly: story)?
- What metrics does our process optimize for?
- How to divide large requirements into issues. When is an issue too small, when is it too large?
- The lifecycle of an issue
- How to write an issue
Issue format
Read the card Project management best practices: Issues.
Gatekeeping
Get familiar with our Gatekeeping process.
In particular you should understand the purpose of:
- Feature branches
- Code reviews
- Commit squashing (and the resulting traceability through
git blame)
Our Merge request checklist
Read the card Before you make a merge request: Checklist for common mistakes
Include the checklist in the description of all future merge requests and try to tick all boxes. You can ignore the translation and pagination requirements for now as they are taught later on.
Deploying production
Understand the steps involved in deploying changes to production.
For this, take a look at geordi gem and examine what its deploy task does.
Linear
Learn to use Linear Show archive.org snapshot , our issue tracker and project management tool:
- Work through the Basic Concepts Show archive.org snapshot tutorial
- Browse through a large team using projects and custom views
- Optional: Add the bookmarklet to create commit messages from an issue to your bookmarks
Resources
Read what's new to you, skim what's familiar, skip what you already master. Stop when you can meet the learning goals.
Your agent can also generate an overview, a tutorial or an explanation for anything here, tailored to what you already know. Just ask.
Our process
- 📄 Gatekeeping: guide for developers — feature branches, reviews, squashing
- 📄 Before you make a merge request: checklist for common mistakes — include it in every merge request description
- 📄 Project management best practices: Issues — how we write issues
- 📄 Linear: basic concepts Show archive.org snapshot — our issue tracker; optional: our bookmarklet for commit messages from an issue
Other processes
- 📄 The Scrum Guide Show archive.org snapshot — Scrum defined by its creators, 13 pages
- 📄 Waterfall methodology Show archive.org snapshot — the case for planning everything up front: clear structure, fixed outcome, thorough documentation
- 📄 What is Kanban? Show archive.org snapshot — the lightweight end: as little process as needed, just a board with work-in-progress limits and lots of communication. Our own process is inspired by this.
- 📄 Agile vs. waterfall Show archive.org snapshot — the two mindsets compared
Exercises
Set up your Linear team
Configure a Linear team for your MovieDB work. This is where all your future exercises are tracked — including follow-up work when a story is rejected in a mentor review.
Set up the team's workflow with the following states. The bold groups are fixed by Linear; the states within them can be configured freely:
-
Backlog
- Backlog
-
Unstarted
- Todo
- Rejected
-
Started
- In Progress
- Merge Request
-
Completed
- Deployed
-
Canceled
- Canceled
-
Duplicate
- Duplicate
Note
Creating a team or editing its workflow may require permissions you don't have yet. Ask a mentor to help you set this up.
Two changes through the full process
Take two small changes to your MovieDB through the complete process, from requirement to staging:
- Change the title of MovieDB to FilmDB.
- Let users assign each movie a genre, chosen from a fixed selection.
For this exercise, your mentor is both your customer and your code reviewer. Ping them in Slack whenever you think it's their turn in the process.
- For the genre change, have a planning discussion with your agent first: what are the key decisions behind "movies have a genre"? Think storage, the list of genres, existing movies without one, where it shows in the UI. Decide them.
- Write each requirement as an issue in your Linear team. Write it yourself: concise, nicely structured, readable for another programmer — the decisions and the requirement, not an implementation plan. Don't have your agent dump its plan and call it a story. Then ask your mentor for feedback.
- Implement each change following the process: feature branch, merge request with the checklist, review, squashing.
- Deploy the changes to staging.
- Have your mentor accept or reject each issue. Make sure at least one issue is rejected once (e.g. your customer changes their mind: "FilmDB" should actually be "FilmBase") so you practice the workflow for rejects.
Important
From now on, deliver all exercises of further lessons through this process: issue, feature branch, merge request with checklist, mentor review, squash.
Tip
If no merge request option can be found, check in your GitLab settings (general > visibility) if the slider "Merge requests" is activated. If not, do so.
Discuss with your mentor
Some of our clients run Scrum, classic waterfall, or a deliberately lightweight process — as little as a Kanban board and lots of communication. Read up on each (see the resources), then discuss:
- How does each differ from our process?
- What are their pros and cons? Under which conditions would one of them serve a project better than our process?
- Coding agents benefit from thorough pre-alignment. Does that give waterfall-style pre-planning a comeback in the agent age?
