Simplify Product Requirements and Project Status Management post-Jasmine

Introduction

There is plenty to improve on the requirements handling from what we did in Jasmine (managing and decomposing). We need to give PMs all the information they need to answer the question - What is the status of REQ 666? without needing a meeting.

I propose a couple of people working in the background on this to have the tools and infrastructure ready by setting up a small sample project to experiment with gitlab features before we kick off Jasmine+1 to fully be able to exploit its features and develop workarounds for its limitations.

Goals

These are some goals I’ve set for myself to simplify how we manage our work. The main goal is to have a fairly transparent project updates structure that scales well to a distributed team (including community contributions) and doesn’t burden the engineering team with too much process.

Please consider them as food for thought to start this discussion:

  1. EPICs for requirements, Iterations for sprints, Labels for Grouping, Milestones for releases
    We need to revisit how we used Gitlab features and perhaps consider fitting our workflow into gitlab instead of the other way around.

    1. EPICs can bring together all the issues being worked on (by different engineers) towards a requirement.
    2. Iterations will continue to be used as in Jasmine for sprints
    3. This should allow product and project management to control how broad or how narrow our work should be focused for a given sprint by looking at the EPIC (REQ) and Iteration views and mapping to expertise available. (Currently PMs don’t have a clear view of this w/o talking to REQ assignees)
    4. As a design pattern to avoid long, complex REQs that span many sprints, we could look into splitting complex REQs into 2-3 EPICs (e.g. MVP, Beta, Production-Ready). Not ALL REQs, just the big, complex ones.
    5. There could also be templates to decompose a REQ - so we have all the common tasks covered for each REQ e.g. R&D/experimentation, implementation, documentation, marketing/blogpost, infrastructure, etc. so that time is budgeted for these activities more uniformly across REQs.
    6. Consider using milestones to plan feature-freeze, alpha and beta releases.
  2. Automate data-collection for reporting through tools
    We’re a distributed team - engineering meetings should minimize status updates (that can happen offline) and focus on discussing design, solving pressing technical problems.

    1. Add templates for MRs, Issues, EPICs, etc. and have them automatically checked by CI to flag common errors e.g. missing what REQ an MR is closing, or a signoff
    2. Engineers should be able to input their weekly updates in gitlab either from web UI or command-line[1].
    3. EPIC + issue-level comments should be collected by tools every week and then massaged into REQ-level updates by PM. See similar tools[2]
    4. Generate sprint-loading graphs, and REQ-related spread dynamically
    5. Auto-label issues added to an EPIC
  3. Use a single tool
    The OpenProject requirement system is supposed to be a high-level view of the feature roadmap to discuss with partners and show a few fields that gitlab doesn’t handle currently (REQ owner, priority, %complete, backlog vs. scheduled). With EPICs now gaining the ability to aggregate weights in the last release of gitlab, the %complete is doable on gitlab now. Labels can be used to track the status of the REQ.

    1. I propose not to migrate OpenProject for the NewCo migration. OpenProject + Gitlab hasn’t been a seamless experience.
    2. Since gitlab is integral to the engineering team, I propose to move everything to gitlab and retire OpenProject.
    3. Dilute some of our requirements for tools to manage Product Requirements and be prepared to work around gitlab limitations using API tooling and reports.

Known limitations of Gitlab

Gitlab has limitations - can we work around them using API tools or perhaps by diluting our requirements in some cases?

  1. EPICs (mapped to REQ in this proposal) cannot be assigned to a single person - consider dilution of this requirement.
  2. EPICs can not have priorities - how do we deal with low priority REQs that we know we won’t have time for? Labels?
  3. Weights for shared dependencies aren’t tracked correctly (and counted multiple times) - set up best practices to not have issue hierarchies
  4. Projects may not have EPICs (e.g. OSTC/Requirements) but SubGroups may have EPICs (e.g. OSTC/OHOS)
  5. Can EPICs in one subgroup (e.g. OSTC/Requirements) collect issues from other subgroups?

Questions:

  1. What properties are we missing here and who does it affect most?
  2. What additional tools do we need to create to assist with this plan?
  3. Do we need to hire someone to assist with the tools?
  4. Who will own the tools and document the policies?
  5. Where should impromptu work (not directly related to REQ) be accounted? Do we need a catch-all EPIC for each core area?
  6. Would using Gitlab as described here[3] alleviate our reporting issues?
  7. How would we use Gitlab Requirements? These are separate from our REQs which are more like project features.

[1] GitHub - Linaro/jipdate: Linaro JIRA Update Tool
[2] GitHub - ndechesne/jipdate: Linaro JIRA Update Tool
[3] Multi-team planning with GitLab Ultimate - YouTube

cc: @SebS @Adam_Szpilko @jarma @rzr

When adopting a tool, such as GitLab, it is important that we not
only consider how it can fulfil our requirements, as set out in
advance, but also look at how GitLab is designed to accomplish
the same overall goals. Although it might not be in the exact
way we initially thought about it, going down the prepared path
is sometimes preferred to paving your own.

Requirement management is a good example of this.

The above proposal to use Epics for requirements at first seems
as a bit odd choice, as GitLab also has dedicated requirement
management
support (Requirements Management | GitLab).
But looking at the
Issues · OSTC / Requirements · GitLab list, most of
the issues there does not look like what is considered
requirements in GitLab terminology, but more like high-level work
packages, which might actually be a good fit for Epics.
In GitLab requirements are
desribed as "A requirement is an artifact in GitLab which
describes the specific behavior of your product. Requirements are
long-lived and don’t disappear unless manually cleared. ", which
then becomes important to keep ind mind if/when using their
Requirements system.

I believe we could and should distil some real requiements (as
per GitLab terminology) from the current OSTC/requirements
issues, as they are clearly hiding in there, and are supposed to
be more visible.
Requirements should describe something that our project should
continously fulfil, and not something that is
accomplished (once), and then closed.

So I propose that we use both GitLab Epics and GitLab
Requirements, and each for the same purpose as intended by
GitLab. I believe it will help us build some good processes for
the project, and will ensure that GitLab implementation fits
better with what we need.

@esben Are you aware of a way to link requirements (as in GitLab project management requirements) to issues/epics? Is that happening only from the issue to the req entry?

I’ve added Gitlab Requirements to the list of things to think about. Thanks for bringing it up - I’d forgotten about Gitlab Requirements. :slight_smile:

I don’t think there are any specific support for linking to epics and issues. But I think it is less of a problem for those things that are actually a requirement (and not something that should really be an epic).
Requirements are supposed to be related to tests, and GitLab supports keeping track of which requirements are currently satisfied based on CI job output.

@esben So you’re suggesting using the Gitlab Requirement construct only to track perpetual requirements that can be directly linked to CI for now?

Some examples being:

  • All builds should succeed
  • Images should boot on all reference platforms
  • All mandatory ACTS tests should pass
  • No IP compliance red flags in the whitelisted set of supported packages

I hope that I’ll not surprise you (much), but I think we should start with feature sets needed (as @idlethread started doing above). So, each of us (as a function) should express its precise needs, then those use-cases should receive some priorities (e.g must-have or nice-to-have), compiled, workload estimated and … potential benefits (e.g. to answer questions like - what is the clear benefit if this feature was added/changed, how it improves our productivity?). If still viable, however, start looking for a way to have it, develop gaps etc.

All in all, IMO, we should be deeply focused on Jasmine now and treat this exercise in the background unless it’s somehow (business) justified. If it improves our productivity, transparency, visibility etc I’m all for it.

Makes sense?

Agreed, Jasmine will be the main focus but I’ll be spending 1-2 hours a week on answering the questions that need to be answered so we don’t enter December in the same situation as in March/April with a ton of new requirements to decompose and needing to figure out how to tweak our use of gitlab to improve workflows.

Yes, GitLab Requirement management for tracking perpetual requirements, and preferably some that can be tested by CI so we can have automated tracking of which requirements are fulfilled and which are not.

For high-level features, such as fx. “Transparent Gateway Blueprint”, which can be decomposed and at some point in time implemented, and then be done, we should use epics.

1 Like

I’ve started capturing use cases for the Jasmin+1 process here Sign in · GitLab so at least we know what is expected, what we’re missing, what is easy to get and e.g. what is not (easily) achievable.
Feel free to pitch in and to add to this file.

@SebS This is a great list to start with!

I’d like to address each of those points in the thread here so everyone can contribute. If that is OK, can you post that list here?

Feel free to add to this list. However, you should use the formula: “[SCOPE][PRIORITY] As a function I would like something to be …” (one use case per point)

  1. [PDM][MUST-HAVE] as a requirement owner I would like to see quantified value of progress for given requirement (e.g. 56% work finished)

  2. [PDM][MUST-HAVE] as a requirement owner I would like to see MergeRequests issued recently to fulfil given requirement (the most recent first)

  3. [PDM][MUST-HAVE] as a requirement owner I would like to see MergeRequests closed recently to fulfil given requirement (the most recent first)

  4. [PDM][MUST-HAVE] as a requirement owner I would like to see which parts of the s/w (e.g. docs, coreos etc) associated MergeRequests impact

  5. [PDM][MUST-HAVE] as a requirement owner I would like to see source of given requirement (e.g. “market trend”, “competetive gap” etc)

  6. [PDM] as a requirement owner I would like to see work load estimated for given requirement

  7. [PDM] as a requirement owner I would like to see confidence level of given requirement

  8. [PDM] as a requirement owner I would like to see accountable person for given requirement

  9. [PDM][MUST-HAVE] as a requirement owner I would like to see target release for given requirement

  10. [PDM] as a requirement owner I would like to see risks for given requirement

  11. [PDM] as a requirement owner I would like to see blockers (if any) for given requirement

@SebS

Points 1-4, 6 and 9 can only be addressed by better decomposition of requirements into engineering tasks in gitlab and better use gitlab aggregation features - the reason why I started this thread. So we are aligned on these points.

I’ve suggested coming up with a template to use to decompose requirements so we don’t forget things or leave till the last minute things like documentation, backend infrastructure changes, IP compliance checks, etc. We can also figure out how to break large, long-running requirements into 2-3 smaller REQs so we have intermediate deliveries. Other ideas are welcome.

Point 10 should be documented inside the REQ itself.

Point 11 blockers will show up automatically when EPICs and Issues in Gitlab depend on another EPIC and Issue, won’t they?

That leaves points 5, 7 and 8. 5 may easily be implemented as labels. 7 and 8 are not directly supported by Gitlab and need workarounds.

  1. [DEV] As a developer I would like to be able to compare the time spent on an issue (and epic), as a minimum when it is closed/done, for the purpose of improving future estimation of other issues and epics.
  2. [DEV] As a developer I would like to be able to specify and track testable requirements, with automatic (CI) evaluation of which requirements are currently satisfied.
1 Like
  1. [DEV] I should have the ability to see the decomposed issues/epic from a requirement. This would aid in validating and tracking the decomposition level.
  2. [DEV] I want to be able to be provided with the priority at every level (issue, epic, req). Also, this information should be consistent across types - for example, a high priority requirement should have high priority decomposed items.
  3. [DEV] Estimation, time spent and weight should be part of the issue’s data and considered part of the development cycle.
  4. [DEV] The items (issues, epics etc.) should provide the dependency chain to other items (blocked-by, blocking etc.)
1 Like
  1. [DEV] I would like to be able to see the level of analysis of the requirements: for example the estimations are only rough as the solution is just a vague idea vs. someone has already done research work on it
1 Like

Thanks for the participation. I think we’ll keep open house by tomorrow for new/last ideas. In the meantime, I’ve started doing analysis how it could be implemented with GL-only approach (let’s see how it goes).
Next I should try to migrate some of our reqs/epics to playground group, then we can call a meeting / sync offline and decided further. I’ll keep you posted here.

Here is a link to play with EPIC-based approach.

I’ve taken an approach, that if given issue has at least one subissue (a dependency) in OSTC group, in the Playground it becomes an epic, otherwise, it it’s just a task. Play with that freely and pls feedback here.