3. Project Boards
All projects will use a Kanban style board to track progress. On Github items on boards are called "issues". You may also hear these referred to as tickets or user stories. User stories are a specialized way of writing a ticket/issue and there is a special page to help you learn how to do that: Writing Tickets & User Stories.
* For the purpose of this wiki, in order to be clear and not cause confusion, we will refer to issues/tickets/user stories as simply "tickets".
Business Tasks are located on the Business Repo Project Board: https://github.com/CodeDoesGood/business/projects/2
Team Tasks are located on their individual Team Project Boards. https://github.com/orgs/CodeDoesGood/projects
The team project boards are at the organizational level. The Business Project Board is a repository level project board, this is the same for development project boards.
It is extremely important that proper process is followed when dealing with tickets and Project boards. This is the primary method used at CodeDoesGood to supervise the project. We understand it can take some time to get comfortable with ticket management and using a Kanban style board if it is new to you and we will be forgiving of mistakes at first. However, any volunteer who continually refuses to follow the process outlined on this page will eventually be removed from the project. Anytime a volunteer does not follow process it causes human resources debt -- in simple words, this means it costs us time. We are all volunteers and CodeDoesGood can't exist if our volunteer time is not used efficiently.
In fact, that is one of our guiding principles: Strict procedures ensure efficient use of volunteer time.
This is the most important rule of them all. In Progress Tickets must be updated WEEKLY. Even if the update is "no progress made this week". This is very very very important. The reason this is important is that if you do not update the ticket we do not know if you have worked on it, if you have forgotten it, if you are busy, or if you have gone MIA. We do not have time to track people down asking them to update their tickets.
Volunteers who continually do not update their tickets may be removed from their project. Please ensure if you are going to be away for an extended period of time that you update your ticket with that information: "Will be away until ____". We will not remove you for missing a week, do not panic. But if you continue to skip weeks, and we have to talk to you about it many times, you will be removed from the project. The reason for this is because you are not adhering to one of our guiding principles: Strict procedures ensure efficient use of volunteer time.
By not following our outlined procedures you cause more work for everyone else which means our volunteer time is not efficiently used. You can join another project again in the future when you have indicated to us that you have more time and will be able to adhere to our guiding principles.
A Kanban board is basically a board with columns. Usually, these columns are Backlog/Icebox, ToDo, InProgress and Done though other columns could exist and other companies may use them differently. Tickets are moved from one column to the next as they change status. This helps visualize what is being done rather than having a large list and having the status labeled on the list.
We use Github for issue tracking but we use the Kanban version of their issue tracking system. This means that all tickets will show up in the "Issues" tab but we are not using the Issues tab, we use the "Projects" tab instead which is organized to look like a Kanban style board.
To repeat: Please do not use the "Issues" tab on Github. Instead, use the "Projects" tab which will show you the Project Board. If you use the Issues tab you will not be able to put the tickets into the correct column.
A Project Board on Github looks like this:
However there is a problem with the Project Board in that screen shot, can you see what it is?
There is a ticket in the Done column which is open and not actually closed:
In this case, this ticket is supposed to be in the In Progress column. What happened is it is an old ticket that we reopened. When it was reopened the person that reopened it did not drag it to the correct column. It is very important that your ticket is in the correct column.
Here is another common mistake:
This ticket was closed but was never moved to the Done column. When a ticket is closed you must drag it to the Done column. Unfortunately, this does not happen automatically, we must manually change which column it is in.
All project boards will have at least 4 columns, some will have 5 columns. The columns are as follows:
- Backlog/Icebox
- TODO
- In Progress
- Done
- Approved (* optional)
- Any others the lead wants to add
Tickets which are not slated for the upcoming release can be found here. These are sometimes large overarching features like "Add messaging" which will need to be broken down into smaller tickets or they can be already broken down. Do not take tickets from this column. Tickets will be moved from the Backlog to the TODO column only by permission of the Project Organizer. In most cases project volunteers do not need to worry about the Backlog at all, either the Project Organizer will move them or the Project Organizer will ask the Lead Mentor to do it.
Think of the Backlog as a memory dump of things that may need to be done in the future.
These are all the tickets which need to be completed before the project is considered complete.
These are tickets which are currently in progress. If you are working on a ticket it must be in this column.
When you complete a ticket you must both mark it as completed and move it to the Done column. Tickets that are marked completed are not moved automatically, you must do this additional step. This is a limitation of the Github Project Board system.
This column will not be on most projects. If you are on a project that has this column it means the client is heavily involved. Only the client may move tickets from Done to Approved. A ticket in the Approved column means the client has gone through the work and has approved it without finding any defects. If a client finds a defect they will comment on the ticket with the issue and will tag it #defect
One of our guiding principles is that every individual is autonomous, masterful, and has a purpose. If you are not sure what this means you can read more on our page about distributed authority.
Being autonomous means we empower our volunteers to make their own decisions. We trust you because we have laid out a strict process for you to follow regarding things that matter. As long as you follow the processes and procedures we have laid out, we trust that any decision you make will be in the best interest of both yourself and of CodeDoesGood.
So, ticket assignment, who does that? The answer is no one :) You will choose tickets yourself. Tickets should be ordered in the board with the most important on top and so you should look at the top few first however we trust you to choose the ticket that makes the most sense to work on next. Any experienced developer should have an idea of what makes the most sense to do next but if they are not sure they can talk to the Lead Mentor. Sometimes it is not clear no matter how much experience you have.
There are some exceptions of course:
- The client may want to see a specific feature before another one and in this situation, the Lead Mentor will request someone take the associated ticket.
- The Lead Mentor may feel you have taken a ticket that is beyond your capacity. Do not be insulted, they understand the scope of what is required better than you do as they understand the full project more than anyone else on the team -- that is after all part of their job. If a Lead Mentor feels you have taken a ticket that is too advanced they will explain this to you and remove you from the ticket, either allowing you to pick another or suggesting one.
- A bug was found in your code or a Lead or Assistant Mentor feels work you submitted will cause technical debt and needs to be changed.
- A Developer may have a ticket assigned to them if the ticket is too advanced for the Hatchlings on the team.
* Remember, you always have the option to say no to a ticket assignment. You are a volunteer, this isn't a job. We want you to be happy and engaged. If you are unhappy with a ticket assignment just let your Lead Mentor know. Have a discussion about it. You never know, there may be a very good reason that ticket was assigned to you and after talking to them you may choose to stay on the ticket. Or maybe not. Communication is vital amoung team members.
Your ticket should fully explain the feature. If you find the description leaves you with questions use the comments to ask your questions by tagging either your Lead Mentor or if appropriate the Project Organizer.
Also, your ticket should fully explain your progress on the feature. This means a Lead or Assistant Mentor should never have to ask you how things are going. If you have problems or there are delays, you need to update the ticket. Remember our guiding principle: Strict procedures ensure efficient use of volunteer time. We do not want anyone to have to message you to find out what is going on because that is a waste of both their time and your time.
To "take" a ticket:
- Assign it to yourself
- Drag it from TODO to In Progress on the Project Board
- Comment with your estimate
After you have taken these steps you can begin work. It is your responsibility to keep the ticket up to date. Any related information such as data required or code taken from other open source projects (this includes large code snippets and solutions for weird bugs found on stack overflow) should be included in a comment. Small code snippets or just general help/solutions do not need to be documented. For example:
Photo upload controller taken from PhotoUploadSample project on Github: http://github.com/sampleuser/photouploadsample/
or
There is a bug in permission requests, as per SO link Used solution by @username
* Note: Bugs such as the example above should also be commented IN the project where the code is used so that a future developer doesn't wonder why you are doing this weird thing and change your code which would reintroduce the bug without them understanding why.
Tickets should also have links to any additional information needed. For example, data or image assets stored in Google drive will be here.
If your original estimate is inaccurate please comment with your new estimate. This is a very important requirement. There is no penalty for this, it simply enables everyone to understand the scope of the task.
The Lead Mentor is responsible for deciding how tags will work. Most projects will use tags to label what part of the app a ticket is from (example #onboarding, #authentication, #messaging, etc) but sometimes tags will be used in other ways and sometimes they will not be used at all.