We use the Kanban software development methodology to run our projects. We manage our projects and version control our code on GitLab, a mostly open-source platform with tools for every stage of the software development lifecycle.
Kanban
Kanban is a method of development developed by Toyota to efficiently manufacture and ship cars. While software is quite different, the idea of a continual, smooth running production line fits well.
We have a Kanban board found at Issues > Boards that covers this production line.
Kanban Board
We have a Kanban Board for each project at Issues > Boards. There is also a MEGA BOARD, that shows all projects at https://gitlab.com/groups/agaric/-/boards .
The pipeline is broken down into the following stages:
- ~"To Do" - an issue deemed a priority and ready to be worked on
- ~Doing - an issue actively being worked on
- ~"In Review" - work that is ready for design and/or code review
- ~Test - work that is ready for testing
- ~Deploy - work that has passed testing and is ready to go live
We strive to have no more than 3 issues in the doing stage for one person. In the To Do column, we keep that between 5 and 10. Enough to have a ready list of issues to work on, while maintaining a sense of priority.
The goal is to move from To Do to Done as quickly as possible, while ensuring quality along the way.
Issue Stages
To Do
An issue that has been decided to be ready to work on by the project manager. They use a combination of relevance to users, complexity and capacity to decide what gets labeled To Do. If something is not labeled as a To Do it should not be worked on.
An issue in the To Do stage should have all information needed for someone to complete it. If it's a user story it has Acceptance Criteria. If it doesn't, add a label Needs Acceptance Criteria, until it does. All issues should have step by step tasks in the Work Required section. If an issue needs the work required outlined, add the label ~"Needs Work Required*.
If a To Do issue is missing information, mark it with ~Needs Clarification and assign it to the project manager.
Doing
An issue moves from To Do to Doing as soon as someone begins working on it. Ideally, that person focuses on that one issue until it is complete (or is passed on to the next person to complete).
As tasks in the Work Required section are completed, check them off.
We keep issues in the Doing stage to a minimum. If there are more than 3 or 4 issues in the Doing stage, it probably means we've overcommited and are switching contexts too much.
In Review
Once an issue is complete, move it to the In Review stage and assign it to someone else who can review the code and/or design. When creating a merge request, include the issue number in your git branch and the merge request will automatically be linked to the issue (fancy!).
Of course, if the issue is not code or design related, it can skip straight to Test.
Test
Once an issue's code and/or design has been reviewed, it can be tested. Assign it to the project manager to test. Testing should happen in the test environment, outlined in the README.md and/or project wiki homepage.
Be sure to read through the README.md for any specific instructions on testing.
If the issue is a user story, use the Acceptance Criteria as a way to test.
Sometimes an issue will be assigned to the client for testing. It's up to the project manager to decide whether that's necessary.
If the issue fails the test, it goes back to the To Do stage, assigned to whoever was working on it last.
Deploy
Once an issue passes testing, it is labeled Deploy and assigned to whoever will deploy it. Consult the README.md for steps on deploying the change to the site. It's best to then test the change once more on the live site to ensure the deployment went as expected.
Closed
Once an issue is successfully deployed close the issue and share the good news with people who care about the change! 🎉
Abandoned
If for some reason an issue is not completed, use the label Abandoned and leave a comment as to why. Then close the issue.
Issue Types
There are three issue types: bugs, tasks and user stories.
We have a template for each, to help members fill in the relevant info. When you create an issue you'll see to the left the three templates to choose from.
User Story
Whenever possible, we write in user stories because they give the fullest picture of what is being built.
A good user story:
- describes what someone can do with the app and what is the business value.
- is written in plain English and must not contain technical terms or implementation details.
- contains keywords that relate to elements of the project.
Gitlab's issue-specific search (at the top of project-name/issues) is good at finding issues; it seems better than the project-wide search.
The issue name follows the structure "[Role] [action]." For example, a "Staff see a registrant's course registration info."
Within the description we then define the Acceptance Criteria for the story.
Acceptance testing is a process to obtain confirmation that a system meets requirements. An acceptance test is a script in plain English executable by a person using the software. A test script contains at least one user action, followed by a paragraph or more describing the expected behavior. Lists, tables and mockups can be used to describe behavior as well.
We loosely structure our acceptance criteria off of a testing framework called Behat, to ease the transition between development and testing.
Given that I am logged in as [role],
when I [action]
then I [result].
Example:
Given that I am logged in as a contributor,
when I leave a comment on a node
then I am redirected to the page from which I left the comment.
If Acceptance Criteria is undefined or is still a work in progress, we add the label ~"Needs Clarification". User stories should only be worked on when acceptance criteria has been approved by the client (ideally someone with the role in the user story).
We also use a Background section to expand on the "why" of the user story. This fuller context helps anyone working on it, design, develop and test authentically.
Tasks
Tasks are for pre-development work (eg: discovery, information architecture, design) that doesn't make sense as a user story. For development purposes, an issue should almost always be a user story or a bug.
Bugs
Our goal is to have no bugs in the bug queues. There are different categories of bugs:
- Programming mistakes leading to error output on the screen (on testing) or a public facing error page (on production). There are usually hints in the logfiles to solve the problem.
- Discrepancies between expected behavior as defined by an acceptance test and actual behavior.
- Common sense violations. This is the most difficult one: A reasonable user expectation is not met but the behavior was not defined in an acceptance test.
Before filing a bug use the search or ask a developer to check whether the same problem has already been reported.
When encountering a bug of the first two categories a bug report is filed following a simple recipe (which we have as an issue template on projects):
- In the issue title, describe the bug in negative language and including keywords, e.g "Posting an event to the feed is broken", "Sending a private message fails".
- In the issue description, write a more detailed version of the title if necessary, and provide additional information including:
- URL of the page where the error has been encountered
- User which you were logged in as at the time or if anonymous
- Date and time the error was encountered (can note "10 minutes ago" if report filed shortly after encountering bug)
- Browser and device / operating system being used when the error has been encountered
- Error messages, if any
- Screenshot(s) if applicable
- What you were trying to do (reference to an acceptance test may cover this)
If a bug was discovered during acceptance testing, put a link to the user story in the description. Referring to a specific step in a test and the unexpected outcome is the most convenient way to describe a bug.
Bugs of the third category indicate that an acceptance test was not comprehensive enough. In that case the acceptance test needs to be amended before fixing the bug. It usually requires talking to the product owner / team about the functionality.
Confidential Issues
A confidential issue is visible to all members with Reporter role or higher which always includes clients. To repeat, confidential issues are NOT hidden from clients. We use confidential issues on public projects for any issue that may contain personally identifying information (e-mail addresses, phone numbers) or otherwise sensitive information (secret API keys).
Skills Required
We use labels to communicate what skills are required of an issue. This helps visualize what type of work is being done. It can also, for example, help us avoid over-committing to one particular type of work. It also helps us spot bottlenecks in our process.
The skills labels are:
- ~Design
- ~Development
- ~Infrastructure
Assignees
The assignee of a task is the person currently responsible for the task. For example, if an issue is ready for review, it should be assigned to whoever is reviewing the issue. Ideally someone should be able to work on an issue if it's assigned to them.
When in doubt, assign issues to Clayton.
Due Dates
Add a due date whenever possible to help set expectations for when something should be ready. The due date should be the date we intend to deploy the change to the live site. Whenever possible, due dates should be decided together with the person responsible for its completion. If not, reach out to the project manager and the assignee to at least give them a heads up.
Gitlab automatically sends an email reminder to the assignee when the due date is approaching.
Documentation
We plan and develop in a way that self-documents as much as possible. This is another benefit of writing user stories. Sometimes, however, extra documentation is helpful.
Technical documentation lives within markdown files in the repository itself. Gitlab renders markdown files in a readable format so even the less technical can easily access and read technical documentation.
End user documentation lives within the website/tool itself whenever possible. In other words, within interfaces the end user is working with in the form of intuitive field labels and help text. If additional documentation is helpful, the interface should link out to those documentation pages. In Drupal, help text should come from the specific module that provides the functionality being documented. For example, documentation on how to create donation forms would come from the Give module, which powers those donation forms.
Project management info such as the video conference line and the roles of people on the project lives in the project's wiki.
Random Tip
The issue description uses a syntax called Markdown. This provides shortcuts for styles such as ## for headings and * for a bulleted list item.
When skipping to a new line, add two spaces to the end. Otherwise, the text shows on the same line. This is helpful for developers and very annoying for everyone else!
More about Markdown - https://gitlab.com/help/user/markdown