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: find your issues, move them through their states, and link your commits to them.
- You can describe Scrum and waterfall 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.
- 📄 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
- 📄 The Scrum Guide Show archive.org snapshot — the official definition, 13 pages; read it to compare Scrum with our process
- 📄 Atlassian: What is Scrum? Show archive.org snapshot — the gentler introduction, with the vocabulary you'll hear from clients
Exercises
- Consider two small changes for your MovieDB
- Change the title of MovieDB to FilmDB
- Add a new attribute to a Movie (like a selection of genre, or duration in minutes)
- Formulate requirements in the forms of stories and ask for feedback from your mentor.
- For each change, follow the process
- Deploy the changes to staging
- Have your mentor accept/reject each issue. Make sure at least one issue is rejected once (e.g. change your mind so "FilmDB" is actually "FilmBase"), so you get to practice the workflow for rejects.
For this exercise, your mentor is both your code reviewer and your customer. Ping them in Slack whenever you think it's their turn in the process.
For all further lessons, you should deliver all exercises through the process.
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.
Other processes
Some of our clients use different processes:
- Scrum
- Waterfall
For each of these processes:
- Understand how they work
- How do they differ from our own?
- What are the pros and cons to our own process? Under which conditions would it be superior to our own process?
