At Linaro, one way or another, we do a weekly report cycle to our groups, members and Linaro.
...
Every month, we also use that information to prepare an /wiki/spaces/EMR/overview, so having accurate information on your progress is important to report them to our members.
The two main update methods are: Weekly emails and Jira update.
Weekly emails was the style most teams used in the past, but they're now redundant with Jira updates, so we strongly recommend you to use Jira directly.
Here are the explanation of both, however, so you can interpret other people's reports, if they still come in that fashion.
Weekly Email
This is simply an email that you should send to your team's mailing list on Fridays, outlining what you have worked on.
You should not use this style from now on, but understanding it will make the Jira style more clear.
Style
The format is usually known as "3x3", with three sections:
- What you have worked on, including references to Jira tickets, short comments and the amount you've worked on each of them.
- What you plan to do next week, including continuations, new tasks, holidays, etc.
- Any serious problems or blocking issues, to raise awareness that you may not be performing as optimally as expected.
Jira + work time
Linking the Jira card (by title, ex. HPC-123) and a short description of what you've done.
Also, this format has a "10/10" time slot, with each slot being "half-day", so that you have 2 slots per day, 10 slots per week.
Those times are approximate and only meant as a general idea of proportional work, not to actually measure time worked.
Most of those reports contain a proportional amount of "time wasted" in meetings, emails, travel, infrastructure.
An example of such a report would be:
This week
=========* [HPC-123] Updated machines to new OS [1/10]
* [HPC-234] Continue working on SVE libraries [4/10]
* [HPC-345] Rebased patch, still waiting for reviews [1/10]
* Meetings, emails, infrastructure [2/10]
* Friday off [2/10]
We usually try not to waste more than one day a week on meetings. If you have too many meetings or you're wasting too much time discussing on lists and reviewing patches, make sure you sync with your tech lead to reduce that time.
Plans for next week
These are normally simple and often obvious tasks, but show which of the tasks you performed this week will need continuation, which will be closing and which new ones will be started.
An example of such a section would be:
Next week
=========* [HPC-123] Run validation on the new OS
* [HPC-234] Finish SVE work, submit a review
* [HPC-345] Hopefully merge the patch
The most important is: keep it simple, keep it short.
Problems and blockages
If you had any major blocking issues, make sure you mention them in here. This section normally doesn't appear on the reviews, as we keep them for special occurrences that not always happen.
For example:
Problems
========* Lab outages meant OS upgrade could only happen on the last day
Usually, those problems should be report only, as this is not meant as a way to make people aware of the blockages. Ie. they should be fixed straight away with the right people as soon as possible, and only mentioned in this report as an explanation why something you planned to do in the previous week hasn't been done.
However, plans not always work as weeks pass, and it's ok to plan one thing on the previous week and do something different this one. For that reason, you don'y have to explain every plan that didn't work in this section, only the major and uncommon occurrences.
For our group, we have chosen to use Jira directly and update the tasks we're working on as often as necessary. This is mainly up to the engineers, but it has to be done at least once a week.
Jira update
Now that we're all using Jira Kanban boards, we can see our progress as it happens. Adding comments directly to the tasks, moving them across the board and creating new tasks on the fly is the best way to report your progress without adding bureaucracy to the process.
Furthermore, project managers and tech leads scan the Jira updates (using weekly and monthly filters based on changes to cards) to know what happened. These updates are scanned by hand and scripts, and they update other project management structures, "Health Check" and "Engineering Update" reports every month.
Rationale
The weekly email was redundant and boring, but it had all the information we needed in a condensed format. So, to completely deprecate it, we need to find similar solutions in Jira that can replace every "feature" of the emails.
But for that to work, the right cards need to be updated as you progress, with comments and changes to the workflow (status, priority, sub-tasks). If engineers don't update the cards, tech leads and project managers have no way to know what has been done.
Three Blocks
Jira + work time
Since we're updating Jira cards, we don't need to reference the cards anywhere. Just adding comments to the cards would be enough.
The updates are better if they're done as soon as you finished a step in your work, or at the end of each day, so that we can have an idea of pace. But that's not always possible, so we shouldn't create strict rules around it.
The minimum amount that is required, however, is at least one update per week, on the cards that you have actually worked on. Simple comments, like "still progressing, now implemented X and Y", are more than enough.
Also make sure to keep the workflow correct. Only keep "In Progress" what you're actively working on that week, and move to "Upstream Review" what's waiting on the community or back to "TODO" what you have put on hold.
Important: Do not update work hours / points on the Jira cards. Those are completely ignored by everyone and every script. Instead, just keep the right cards in the right columns and that's more than we need.
Plans for next week
...
Three Levels
Our Jira has 3 levels:
Initiatives
- Major projects, discussed at the TSC level with vague descriptions and general ideas.
- Owned by the TSC representatives
- Long term (year+ scale)
- Engineers should ignore these
Epics
- Breakdown of initiatives, with concrete expectations, definite tasks
- Owned by the main engineer working on it
- Medium term (week~month scale)
- Engineers should update it at least once a week with TSC updates (not working comments)
Sub-tasks
- Breakdown of epics, where the work actually happens
- Owned by the engineer working on it
- Very short term (day~week scale)
- All working comments, attachments and discussions should go here
TSC members only see Initiatives and Epics, so we keep the noise down on that level and crank it up at the sub-task level. Right now we update the members with a "Health Check" card and the "Engineering Update", so the epics are mostly for organisational purposes. But they still shouldn't have noise, so we do not update them with development comments. All of that go into tasks.
Basic Rules
Managing Epics
If you own an Epic, make sure the tasks beneath it are up-to-date and reflect your current work, at least to a week granularity.
Do not update Epics with comments or attachments, only use it to create new tasks and high-level update once a week. Create as many tasks as you need, whatever makes you more productive.
Feel free to resolve tasks that won't be worked on. The tech-lead will look at all the resolved tasks weekly and close them or ask questions (like where's the docs, commit link, how did you test, etc).
If you finished working on an epic, or need to create a new epic, talk to the tech-lead, so you can close it and properly update the TSC with the result of that work.
This is intended to reduce the noise at the TSC level.
Plans for next week
Open epics are unassigned, meaning no one will work on them any time soon. Once you plan on working with something, assign that card to you (or create a new one and assign it), so that it appears in your "TODO" column.This is essentially the "next week" plan. Given the vague nature of the original plan, and how it could be overruled but new tasks, there's no difference at all
You can keep cards in the TODO column for weeks, as long as you have enough in the In Progress and what's in there is more important than what's in TODO, that's perfectly fine.
We also don't care much about the priority field in the cards, but you can use it for your own benefit.
The only thing that matters to us is:
- regular comments means regular work being done
- cards to be in the right columns
Important: Do not update work hours / points on the Jira cards. Those are completely ignored by everyone and every script. Instead, just keep the right cards in the right columns and that's more than we need.
Problems and blockages
All problems and blockages should be reported immediately at the appropriate channels, copying your internal development list and your tech lead.
Infrastructure problems need to be reported to ITS, Lab and Systems teams or other teams in LEG. Builds and releases reported back to Builds, toolchain, kernel or even LAVA teams.
Long term blockages , the ones that would be reported on the weekly email, warrant moves to the Blocked column, but only after you have reported and followed up in the right channels, should be moved to the "Blocked" column.
These mark tasks as "completely blocked", meaning you cannot work at all without the other teams removing the blockage, and will fire a salvo of urgent requests across all involved teams.
So, if you have a blocked task, but you can do other tasks while you wait for that one task to be unblocked, do Do not move them to the "Blocked" column Blocked column unless:
- The task being blocked is urgent or the most important task you have In Progress, and
- The blockage will not be resolved by waiting, ie, needs working with other teams before solving it.
Overall
The following picture summarises the usage of Jira:
...