Skip to content

Time tracking in GitLab

Wireframes are not shown directly on this issue in order to make it more readable, until we have a more elegant solution on how we display images inside an issue.

Most of the big corporations have teams of developers. Sometimes they treat these teams as external resources, like they were a company within the company. Before starting a project, they ask for the cost of the project, ask about their availability and deadlines. Throughout the project, the dev team sends invoices to the service who requested the work. These invoices are based on the time spent working on the project.

We have an opportunity here to fulfill the needs of these big corporations with built-in time-tracking. Companies are looking to reduce the number of tools they use - it’s perfect for us as we are at the core of any development team by being the tool that manages their code.

Introducing GitLab Time Tracking.

High-level considerations

Like some other things within GitLab, you can interact with time tracking in various ways - through the UI, by reference in a commit message, through the command line. I don't think it’s confusing to interact with a feature in multiple ways, as long as it’s consistent everywhere.

  • The core need is to be able to measure how much time we intend to spend on a given task, and how much time it actually took to do it. These tasks can be
    • Create an issue
    • Write a comment
    • Work on a merge request
  • We should be able to see how much time we’ve spent on tasks on multiple levels:
    • At the Issue or MR level
    • If the Issue/MR is part of a Milestone, at the Milestone level.
  • Time-tracking comes with estimates, so we can measure whether we are on track with any given task.
  • That leads to different powerful reports and a lot of of time-tracking hints throughout GitLab - and we could allow even bigger project management features like Gantt charts in the future.
  • Moonshot (therefore not for v1): provide a chronometer in the UI.
  • Marsshot (not for v2): a command line utility that would let us write things like gitlab start #124 and gitlab pause #124.

EE vs CE

While this feature clearly targets large teams of developers, there is also an interest for smaller teams or even solo developers to measure how much time they spend on their projects. However, I would make the following assumptions:

  • Small teams generally do not need time estimates. If they do, it's because they are small independent dev shops, or agencies, and already use time tracking tools that are linked to a billing software somehow.
  • Small teams generally do not have to care about resource allocations, over time budgeting, or advanced time reporting.

For those reasons, time tracking will be limited to EE.

Specifications

High level lists of changes for this feature (links to internal anchors):

New option in the Admin Settings panel

Settings under admin/application_settings

  • In order to be able to make the right time conversions (42h → 1w 2h), we should be able to define in the administration panel of an instance
    • the number of working days per week, default 5.
    • the number of working hours per day, default 7.
  • Time tracking is set globally in an instance. We don't need a per-project override for this feature.

Link to wireframe

New slash commands

We will create a bunch of new slash commands:

  • /estimate 1w 3j 2h 14m: add an estimate for the task
  • /spend 3w: indicate how much time the task took

Time format follows Jira convention with the sames rules as they have:

  • Default conversion rates are 1w = 5d and 1d = 8h.
  • If we enter a number without anything else (like 2), we will assume it’s 2 hours. This is configurable.
  • If we enter 40h, we will automatically convert this to 5d. This is configurable.

Rules about those slash commands

  • /estimate can be entered in the body of the issue/MR or in a comment. Only the latest /estimate is taken into account, and overrides any other estimates.
  • /spend can be entered in the body or in a comment too. Contrary to /estimate, we will count the total of each occurrence to calculate the spent time on a task. The total count is calculated every time a /spend command is entered.
  • /spend can only be defined by the person who is currently assigned to the issue, in order to prevent having false positive.
  • Issues/MR can have an estimate only, a time spent only or both.

Changes in the sidebar of an issue/MR

  • We will display both the Estimate and the Spend fields in the sidebar.
  • Only the Estimate field is editable in the sidebar. The reason for this is that there is only one valid source of Estimate field in an Issue or MR, but there can be multiple occurrences of time spent. If we allow the override of the time spent in the sidebar, it becomes messy UX wise, as people will still be able to enter subsequent /spend entries in the issue. And in this case, how would we calculate the total?
  • Both fields are optional and we can have data in one field and not the other.
  • Spend time information is the total of each /spend mention in an issue.
  • If an estimate has been provided, Spend time information also indicates the difference between the time that was estimated and the time it actually took, represented in %.

Link to wireframe

Logs in issues and MR timelines

  • When we either change the estimate through the sidebar or with a slash command, a new action is logged in the issue or MR.
  • Same for adding a time spent.

Link to wireframe

New filter in the issues list

  • We should create a new filter in the list of issues. For instance, that will allow developers to pick issues that are supposedly quick to do (ie less than an hour).

Link to wireframe

New icon indicating estimates in list of issues

  • As we have a new Estimate filter on list of issues, we should indicate the estimate on each issue (very unsure about the wireframe for this one, I need UX to tackle that).

Link to wireframe

Changes in the Issues board

  • The issue board is a tool to sort issues and take decision quickly on what to do next. Estimates are actually great metrics to know if we should work on something. Therefore I propose to add a icon next to issues that have time tracking data.
  • When mouse over on this icon, we show a tooltip that indicates the estimate and the time already spent on the issue.

Link to wireframe

Changes in the list of milestones

  • We need to provide a quick way of knowing which milestone has taken more hours than estimated.

Link to wireframe

Changes in the detail of a milestone

  • It's important for a decision maker to give a bunch of metrics when viewing a milestone
    • know how much time we've spent total in a given milestone (man-hours)
    • are we on track and have we spent all the budget (hours) that was allocated?

Note: I don't think we need the big green bar anymore. We can replace it by a pie chart. The most important information for a decision maker is not this big green bar.

Link to wireframe

New API methods

We will provide new APIs to interact with this feature.

  • At the issue level
    • Read/write time spent
    • Read/write estimates
  • At the MR level
    • Read/write time spent
    • Read/write estimates
  • At the milestone level
    • Get the total time spent
    • Get the total estimates
  • At the project level
    • Get the total time spent
    • Get the total estimates

Reports

This reports section is a WIP.

Reports are a huge part of the feature and is what will bring value. We have three ways of displaying reports: simple data, graphs and tables.

Break downs of the reports:

  • Group reports

    • Questions we try to address with these reports:
      • As a manager of a group, how much time is spent in total in all the projects of this group?

  • Per user reports

    • Questions we try to address with these reports:
      • As a user, how much time have I already spent in total? Per project?
      • As a user, how many times am I over the estimates?
      • As a user, how much time do I spend on average on an issue?
      • As a user, what is the issues that took much of my time the most, regardless of the projects I've worked on?
    • Reports:
      • Data: Total time spent (overall | time range)
      • Data: Average time spent + average estimates on issues the user participated in (overall | time range)
      • Data: Average time spent + average estimates on MRs the user participated in (overall | time range)
      • Table: per project the user has access to, total time spent + total estimates + variation in % between the two, on issues the user participated in.
      • Table: list of issues and MR the user participated in, in all projects the user has access to, ordered by total time spent, sortable by total time spent or estimates (overall | time range)

  • Project reports

  • Issues/MR reports

  • Milestones reports

External integrations

Because we provide APIs for this feature, integrations with popular time tracking and billing softwares will be possible. This will probably something we'll have in the future though, not at launch.

How to measure KPIs for this feature

TBD

Tasks

  • Implement the /estimate command
  • Implement the /spend command
  • Implement the Estimate and Spend sidebar component
  • When adding/changing estimate and time spent, add a journal entry in the issue/MR
  • Implement the Settings panel
  • Implement a new filter in the list of issues
  • Implement the list of miletones view
  • Implement the detail of a milestone view

Questions:

  • Q1: should we allow a per-project feature activation?

Out of scope

  • Time tracking in commits
  • Budget/billable hours

References/links

cc @JobV @markpundsack @sytses

(random notes: someone who want to know how much time we spent on a project, MR, issue)