[Issue 854] ADR for 30k deliverable reporting strategy

[widal001]

Summary

Creates ADR for our 30k deliverable reporting strategy which:

1. Recommends a consistent strategy for assigning issues to a parent 30k deliverable across reporting channels
2. Recommends an approach to limiting the number of 30k deliverables that appear in our reports

Fixes #854

Time to review: 10 mins

Changes proposed

What was added, updated, or removed in this PR.

Creates decisions/adr/2023-12-15-deliverable-reporting-strategy.md

Context for reviewers

Testing instructions, background context, more in-depth details of the implementation, and anything else you'd like to call out or ask reviewers. Explain how the changes were verified.

Following our conversation on 1/5/24, we've decided to proceed with using a deliverable column to assign a task level issue to a 30k deliverable. We'll plan to reassess in an upcoming retrospective.

Additional information

Screenshots, GIF demos, code examples or output to help show the changes working as expected.

[lucasmbrown-usds]

A very thoughtful analysis - well done!

I have some questions about the recommendation for the way we assign issues to deliverables, maybe we can talk it out verbally after you review.

I also wonder if it would be helpful to describe the human-centered UX of the recommended options. For instance, you could write out the steps for "How to create a new 30k and have it reflected in reporting", and "How to update the name of an existing 30k and have it consistently update reporting". This could help us get a sense of the UX of maintaining this option going forward.

[andycochran]

LGTM! (Left a couple nits you can address or ignore.)

[andycochran]

Suggested change

	- When creating a new Issue, it's not sufficient to add that Issue to a Milestone; it must also be added to the 30k deliverable for that Milestone for reporting purposes. We will need to monitor for Issues that do not have a 30k and triage them regularly.

[andycochran]

I'm still wondering if we might make it easier to associate Issues with the appropriate Milestone and 30k deliverable. One idea that comes to mind is prefixing all Milestone titles with an ID that matches the ID of the deliverable — e.g.:

• Issue #n has the title "[30k ]: My Deliverable Name"
• The deliverable column uses that Issue's ID in its title, e.g. "[#n]: My Deliverable Name"
• Milestones that address that deliverable use that same ID in their titles, e.g. "[#n]: My Milestone Name"
• Then, when creating an Issue, it is clear that you should choose a Milestone and deliverable that are prefixed with same ID. This may make it easier to choose the right deliverable when it is not apparent which 30k a Milestone addresses, or for individual contributors who are closer to the ground, more concerned with Milestones, and unsure with which 30k an individual ticket addresses.

[widal001]

One idea that comes to mind is prefixing all Milestone titles with an ID that matches the ID of the deliverable

I like this idea as a way to make the intended deliverable clear, though I worry it could introduce discrepancies if an issue gets reassigned to a different deliverable but forgets to update the title of the issue as well.

Part of the reason we created this ADR was to limit the "sources of truth" that associate an issue to a deliverable.

[sumiat]

Thanks for putting this together and for the thoughtful evaluation!

[lucasmbrown-usds]

Thanks for the very thorough analysis. LGTM!

[sarahknoppA6]

yay! there's been so much work and discussion on this, I think this looks right to me.