From b487cc3d7cd507c2ec47f45a9bc327d221fd5e1d Mon Sep 17 00:00:00 2001 From: widal001 Date: Mon, 18 Dec 2023 12:14:45 -0500 Subject: [PATCH 01/14] feat: Adds deliverable reporting strategy ADR --- ...23-12-15-deliverable-reporting-strategy.md | 102 ++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md diff --git a/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md b/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md new file mode 100644 index 000000000..69eda89e3 --- /dev/null +++ b/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md @@ -0,0 +1,102 @@ +# 30k ft deliverable reporting strategy + +- **Status:** Active +- **Last Modified:** 2023-12-18 +- **Related Issue:** [#854](https://github.com/HHS/simpler-grants-gov/issues/854) +- **Deciders:** + - Lucas Brown + - Billy Daly + - Sarah Knopp + - Sumi Thaiveettil + - Aaron Couch +- **Tags:** analytics, github + +## Context and Problem Statement + +In order to report on the progress we're making toward our 30,000 foot deliverables (30k deliverables), we need to be able to connect those deliverables to the ground-level tasks that need to be completed for delivery. Being able to reliably identify which tasks are required for a given deliverable not only enables us to report key metrics like burnup or percent completion for each deliverable, it also allows us to understand which deliverables are being worked on within a given sprint. + +Currently, however, we do not have a consistent strategy for indicating which 30k deliverable a given issue is associated with. For custom reporting, we have been using the milestone that an issue is assigned to as a proxy for its 30k deliverable, and for our sprint board, we've been using issue labels to drive filtering and reporting. The fact that we represent this hierarchy differently across reporting channels creates an additional maintenance overhead and increases the likelihood of presenting conflicting information between reports. + +Additionally, as the number of 30k deliverables defined for the project grows, we'll need to adjust our strategy for including them in project reporting. By default, we include all 30k deliverables in our reports, but this results in a large chart where in which many deliverables have no points or issues assigned to them. In order to more accurately reflect the status of our deliverables, we need to determine when and how to include them in reporting. + +In light of these needs, the goal of this ADR is to: + +1. Recommend a consistent strategy for assigning issues to a parent 30k deliverable across reporting channels +2. Recommend an approach to limiting the number of 30k deliverables that appear in our reports + +## Decision Drivers + +### Assigning issues to deliverables + +Our recommended strategy for assigning issues to a given 30k deliverable should consider the following criteria: + +- Users assigning an issue to a 30k deliverable should only need to update that value in one place +- Users should be able to search or filter for the issues assigned to a given 30k deliverable +- Users should be able to group by 30k deliverables in the sprint board +- The relationship between issues and 30k deliverables should be consistently represented across all reports + +### Limiting the 30k deliverables included in reporting + +Our recommended approach to limiting the deliverables that are included in reporting : + +- The logic for including a 30k deliverable in reporting should be clear and easy to understand +- Users should be able to add or remove a given 30k deliverable from reports without having to change the underlying logic +- If necessary, users should be able to change the reporting logic without rewriting significant sections of the source code + +## Options Considered + +### Assigning issues to deliverables + +- Add the issue to a milestone that represents a 30k deliverable +- Tag the issue with a label that represents a 30k deliverable +- Use a reserved phrase to tag a 30k deliverable in the body of the issue + +### Limiting the 30k deliverables included in reporting + +- Use a label to indicate when a deliverable should be included in reporting +- Use the status of the deliverable in the provisional roadmap project + +## Decision Outcome + +Chosen option: "{option 1}", because {justification. e.g., only option which meets a key decision driver | which satisfies x condition | ... }. + +### Positive Consequences + +- {e.g., improved performance on quality metric, new capability enabled, ...} +- ... + +### Negative Consequences + +- {e.g., decreased performance on quality metric, risk, follow-up decisions required, ...} +- ... + +## Pros and Cons of the Options + +### {option 1} + +{example | description | pointer to more information | ...} + +- **Pros** + - Good, because {argument a} + - Good, because {argument b} + - ... +- **Cons** + - Bad, because {argument c} + - ... + +### {option 2} + +{example | description | pointer to more information | ...} + +- **Pros** + - Good, because {argument a} + - Good, because {argument b} + - ... +- **Cons** + - Bad, because {argument c} + - ... + +## Links + +- [{Link name}](link to external resource) +- ... From 43d05f97d3966430a46312b33c827be74e364da6 Mon Sep 17 00:00:00 2001 From: widal001 Date: Mon, 18 Dec 2023 14:10:35 -0500 Subject: [PATCH 02/14] feat: Evaluates options for assigning issues to deliverables --- ...23-12-15-deliverable-reporting-strategy.md | 94 ++++++++++++++++--- 1 file changed, 83 insertions(+), 11 deletions(-) diff --git a/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md b/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md index 69eda89e3..a9e7107b8 100644 --- a/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md +++ b/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md @@ -32,7 +32,7 @@ Our recommended strategy for assigning issues to a given 30k deliverable should - Users assigning an issue to a 30k deliverable should only need to update that value in one place - Users should be able to search or filter for the issues assigned to a given 30k deliverable -- Users should be able to group by 30k deliverables in the sprint board +- Users should be able to group by 30k deliverables in the sprint board and in GitHub insights reporting - The relationship between issues and 30k deliverables should be consistently represented across all reports ### Limiting the 30k deliverables included in reporting @@ -43,20 +43,22 @@ Our recommended approach to limiting the deliverables that are included in repor - Users should be able to add or remove a given 30k deliverable from reports without having to change the underlying logic - If necessary, users should be able to change the reporting logic without rewriting significant sections of the source code -## Options Considered +## Options considered ### Assigning issues to deliverables -- Add the issue to a milestone that represents a 30k deliverable -- Tag the issue with a label that represents a 30k deliverable -- Use a reserved phrase to tag a 30k deliverable in the body of the issue +- **Milestones:** Add the issue to a milestone that represents a 30k deliverable +- **Labels:** Tag the issue with a label that represents a 30k deliverable +- **Deliverable column:** Add a custom "deliverable" column to the GitHub projects with values representing each 30k deliverable +- **Reserved phrase:** Use a reserved phrase to tag a 30k deliverable in the body of the issue ### Limiting the 30k deliverables included in reporting -- Use a label to indicate when a deliverable should be included in reporting -- Use the status of the deliverable in the provisional roadmap project +- **Label:** Use a label to indicate when a deliverable should be included in reporting +- **Status:** Use the status of the deliverable in the provisional roadmap project +- **GitHub action:** Explicitly list the deliverables to include in the GitHub action for reporting -## Decision Outcome +## Decision outcome Chosen option: "{option 1}", because {justification. e.g., only option which meets a key decision driver | which satisfies x condition | ... }. @@ -70,9 +72,65 @@ Chosen option: "{option 1}", because {justification. e.g., only option which mee - {e.g., decreased performance on quality metric, risk, follow-up decisions required, ...} - ... -## Pros and Cons of the Options +## Evaluation - Assigning issues to deliverables -### {option 1} +### Milestone + +This option involves creating a milestone for each 30k deliverable and assigning issues to that milestone if they are required for delivery of that 30k. + +> [!NOTE] +> This is a slightly different use of milestones than the project currently supports. Right now, the engineering team can create multiple milestones for a given 30k deliverable and reporting is driven by tagging the parent 30k deliverable in the description of the milestone. This new approach would require a *single* milestone per 30k deliverable and all tickets associated with that deliverable would need to be added to the milestone to be included in reporting. + +- **Pros** + - Ensures that there is just one source of truth for the list of issues associated with a given 30k deliverable. + - Supports filtering both within the repository and within GitHub projects (e.g. roadmap and sprint board). + - Supports grouping both within the GitHub projects and within GitHub insight reporting. +- **Cons** + - Prevents the engineering team from using GitHub milestones to organize and group related issues outside of the 30k deliverable framework. + - Milestones that represent 30k deliverables will have a *lot* of tickets unless we work on downscoping 30k deliverables. + - Does not support customizing the order of the groups on the sprint board when grouping by milestone -- milestones can only be sorted alphabetically. + +### Label + +This option involves creating a label for each 30k deliverable with a consistent prefix (e.g. `30k: Public launch`) and then applying this label to each of the issues required for delivery of that 30k. + +- **Pros** + - Allows the engineering team to continue to use GitHub milestones to organize issues into units of work that make sense to them. + - Supports filtering both within the repository and within GitHub projects (e.g. roadmap and sprint board). +- **Cons** + - Does not easily support grouping in GitHub projects or GitHub insights reporting. + - Will result in a large number of labels if 30k labels aren't deleted once a 30k deliverable is complete. + +### Deliverable column + +This option involves creating a single select "deliverable" column in the GitHub projects, with values for each 30k deliverable, and then selecting the corresponding "deliverable" value for each issue added to the project. + +- **Pros** + - Allows the engineering team to continue to use GitHub milestones to organize issues into units of work that make sense to them. + - Supports filtering within GitHub projects (e.g. roadmap and sprint board). + - Supports grouping within GitHub projects and within GitHub insight reporting. + - Supports customizing the order of groups on the sprint board when grouping by deliverable -- for example we can make "Static site public launch" appear above "GET Opportunities" even though GET opportunities would be first alphabetically. +- **Cons** + - Does not support filtering or searching within the GitHub repository. + - Will result in a large number of values for the deliverable column if not regularly maintained. + - List of deliverable column values will have to be maintained separately across projects -- inconsistencies between these lists may introduce bugs in custom reporting. + +### Reserved phrase + +This option involves tagging a 30k deliverable from the body of each issue using a reserved phrase (e.g. "30k deliverable: #123"). It would function much like [linking a pull request to an issue][linking pull requests] does in GitHub. + +- **Pros** + - Allows the engineering team to continue to use GitHub milestones to organize issues into units of work that make sense to them. + - Easy to parse in custom reporting. +- **Cons** + - Does not support filtering or searching within the GitHub repository. + - Does not support filtering or searching within GitHub projects (e.g. roadmap or sprint board). + - Does not support grouping within GitHub projects or GitHub insight reporting. + - Very difficult to audit or maintain programmatically. + +## Evaluation - Limiting 30k deliverables in reporting + +### Label {example | description | pointer to more information | ...} @@ -84,7 +142,19 @@ Chosen option: "{option 1}", because {justification. e.g., only option which mee - Bad, because {argument c} - ... -### {option 2} +### Status + +{example | description | pointer to more information | ...} + +- **Pros** + - Good, because {argument a} + - Good, because {argument b} + - ... +- **Cons** + - Bad, because {argument c} + - ... + +### GitHub action {example | description | pointer to more information | ...} @@ -100,3 +170,5 @@ Chosen option: "{option 1}", because {justification. e.g., only option which mee - [{Link name}](link to external resource) - ... + +[linking pull requests]: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests#linking-a-pull-request-to-an-issue From 0661f65747f7832a91711d36918626225a71f36c Mon Sep 17 00:00:00 2001 From: widal001 Date: Mon, 18 Dec 2023 15:03:36 -0500 Subject: [PATCH 03/14] feat: Evaluates options for filtering 30k deliverables --- ...23-12-15-deliverable-reporting-strategy.md | 54 +++++++++++-------- 1 file changed, 32 insertions(+), 22 deletions(-) diff --git a/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md b/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md index a9e7107b8..121599678 100644 --- a/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md +++ b/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md @@ -32,7 +32,7 @@ Our recommended strategy for assigning issues to a given 30k deliverable should - Users assigning an issue to a 30k deliverable should only need to update that value in one place - Users should be able to search or filter for the issues assigned to a given 30k deliverable -- Users should be able to group by 30k deliverables in the sprint board and in GitHub insights reporting +- Users should be able to group by 30k deliverables in the sprint board and in [GitHub insights reporting][github-insights] - The relationship between issues and 30k deliverables should be consistently represented across all reports ### Limiting the 30k deliverables included in reporting @@ -132,43 +132,53 @@ This option involves tagging a 30k deliverable from the body of each issue using ### Label -{example | description | pointer to more information | ...} +This option involves creating a label that indicates when a deliverable should be included in reporting (e.g. "add to report") and then filtering for this label in our custom reporting. + +> [!NOTE] +> The code should be configured to accept an arbitrary set of labels as filters, so that if the label changes, we only need to change the top-level configuration and not several lines of the source code. - **Pros** - - Good, because {argument a} - - Good, because {argument b} - - ... + - Makes the choice to include a deliverable in a report explicit and easy to understand. + - Enables users to add or remove deliverables from reporting without changing the logic or the source code. + - Makes it easy to change the logic that determines which issue labels are used to include/exclude issues from reporting. - **Cons** - - Bad, because {argument c} - - ... + - Decouples reporting logic from the status of ongoing deliverables. **Note:** this could be a pro or a con depending on how tightly coupled we want reporting and delivery management to be. + - Adds to the already long list of labels in the repository. ### Status -{example | description | pointer to more information | ...} +This option involves filtering the deliverables that are included in reporting based on their status in the provisional roadmap project. For example, we may only want to report on deliverables that have the status "In progress" or "Planning". + +> [!NOTE] +> The code should be configured to accept an arbitrary set of statuses as filters, so that if we want to change which statuses are included, we only need to change the top-level configuration and not several lines of the source code. - **Pros** - - Good, because {argument a} - - Good, because {argument b} - - ... + - Enables users to add or remove deliverables from reporting without changing the logic or the source code. + - Makes it easy to change the logic that determines which statuses are used to include/exclude issues from reporting. + - Keeps the reporting and delivery management in sync. - **Cons** - - Bad, because {argument c} - - ... + - Logic behind which deliverables are included in reporting is not as explicit as having a dedicated label. + - Requires the reporting logic to be tightly coupled with the rules for assigning deliverable status. ### GitHub action -{example | description | pointer to more information | ...} +This option involves specifying the deliverables we want to include in the reporting within the GitHub action itself, either by name or by issue number. + +> [!NOTE] +> The code should be configured to accept an arbitrary list of issue titles or numbers, so that if we want to change which deliverables are included, we only need to change the top-level configuration and not several lines of the source code. - **Pros** - - Good, because {argument a} - - Good, because {argument b} - - ... + - Makes the choice to include a deliverable in a report explicit and easy to understand. + - Prevents someone from accidentally removing a deliverable from reporting by changing a label or status. - **Cons** - - Bad, because {argument c} - - ... + - Decouples reporting logic from the status of ongoing deliverables. **Note:** this could be a pro or a con depending on how tightly coupled we want reporting and delivery management to be. + - Does not allow users to add or remove deliverables from reporting without changing a configuration file. + - Prone to error if users enter the wrong issue title or number. ## Links -- [{Link name}](link to external resource) -- ... +- [Linking pull requests to issues][linking-pull-requests] +- [GitHub insights reporting][github-insights] -[linking pull requests]: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests#linking-a-pull-request-to-an-issue +[linking-pull-requests]: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests#linking-a-pull-request-to-an-issue +[github-insights]: https://docs.github.com/en/issues/planning-and-tracking-with-projects/viewing-insights-from-your-project/about-insights-for-projects From 3d70ab188c82f623b11b729db6599e5731d647cc Mon Sep 17 00:00:00 2001 From: widal001 Date: Mon, 18 Dec 2023 15:07:54 -0500 Subject: [PATCH 04/14] refactor: Adds missing deciders and adds todo --- ...23-12-15-deliverable-reporting-strategy.md | 29 +++++++++++++------ 1 file changed, 20 insertions(+), 9 deletions(-) diff --git a/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md b/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md index 121599678..12d15df1b 100644 --- a/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md +++ b/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md @@ -5,10 +5,11 @@ - **Related Issue:** [#854](https://github.com/HHS/simpler-grants-gov/issues/854) - **Deciders:** - Lucas Brown - - Billy Daly - Sarah Knopp - Sumi Thaiveettil - Aaron Couch + - Esther Oke + - Billy Daly - **Tags:** analytics, github ## Context and Problem Statement @@ -58,19 +59,29 @@ Our recommended approach to limiting the deliverables that are included in repor - **Status:** Use the status of the deliverable in the provisional roadmap project - **GitHub action:** Explicitly list the deliverables to include in the GitHub action for reporting -## Decision outcome +## Decision outcomes -Chosen option: "{option 1}", because {justification. e.g., only option which meets a key decision driver | which satisfies x condition | ... }. +### Assigning issues to deliverables -### Positive Consequences +TODO: Trying to decide between the labels option and the deliverable column option. -- {e.g., improved performance on quality metric, new capability enabled, ...} -- ... +- **Positive outcomes** + - {e.g., improved performance on quality metric, new capability enabled, ...} + - ... +- **Negative outcomes** + - {e.g., decreased performance on quality metric, risk, follow-up decisions required, ...} + - ... + +### Limiting the 30k deliverables included in reporting -### Negative Consequences +TODO: Trying to decide between the label option and the status option. -- {e.g., decreased performance on quality metric, risk, follow-up decisions required, ...} -- ... +- **Positive outcomes** + - {e.g., improved performance on quality metric, new capability enabled, ...} + - ... +- **Negative outcomes** + - {e.g., decreased performance on quality metric, risk, follow-up decisions required, ...} + - ... ## Evaluation - Assigning issues to deliverables From dfc9101589223b1c8db3d15e06ab69e8098ff5bf Mon Sep 17 00:00:00 2001 From: widal001 Date: Mon, 18 Dec 2023 15:22:06 -0500 Subject: [PATCH 05/14] fix: Typo in decision drivers section --- .../decisions/adr/2023-12-15-deliverable-reporting-strategy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md b/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md index 12d15df1b..f03837372 100644 --- a/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md +++ b/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md @@ -38,7 +38,7 @@ Our recommended strategy for assigning issues to a given 30k deliverable should ### Limiting the 30k deliverables included in reporting -Our recommended approach to limiting the deliverables that are included in reporting : +Our recommended approach to limiting the deliverables that are included in reporting should consider the following criteria: - The logic for including a 30k deliverable in reporting should be clear and easy to understand - Users should be able to add or remove a given 30k deliverable from reports without having to change the underlying logic From d51afe03eb60ff27032c8ab3a20408c201f3e978 Mon Sep 17 00:00:00 2001 From: widal001 Date: Tue, 19 Dec 2023 17:37:11 -0500 Subject: [PATCH 06/14] feat: Adds tips with bottom line details about options --- ...23-12-15-deliverable-reporting-strategy.md | 32 +++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md b/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md index f03837372..353b3e142 100644 --- a/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md +++ b/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md @@ -92,6 +92,12 @@ This option involves creating a milestone for each 30k deliverable and assigning > [!NOTE] > This is a slightly different use of milestones than the project currently supports. Right now, the engineering team can create multiple milestones for a given 30k deliverable and reporting is driven by tagging the parent 30k deliverable in the description of the milestone. This new approach would require a *single* milestone per 30k deliverable and all tickets associated with that deliverable would need to be added to the milestone to be included in reporting. +> [!TIP] +> **Bottom line:** This is the best option if we: +> - want a consistent way to filter and group issues by deliverable across all GitHub projects and reporting as well as within the repository +> - but are okay with preventing the engineering team from using milestones to organize issues into smaller units of work + + - **Pros** - Ensures that there is just one source of truth for the list of issues associated with a given 30k deliverable. - Supports filtering both within the repository and within GitHub projects (e.g. roadmap and sprint board). @@ -105,6 +111,11 @@ This option involves creating a milestone for each 30k deliverable and assigning This option involves creating a label for each 30k deliverable with a consistent prefix (e.g. `30k: Public launch`) and then applying this label to each of the issues required for delivery of that 30k. +> [!TIP] +> **Bottom line:** This is the best option if: +> - we want a consistent way to filter issues by deliverable in the repository and across GitHub projects +> - but can compromise on being able to **group** by deliverable in GitHub projects or reporting + - **Pros** - Allows the engineering team to continue to use GitHub milestones to organize issues into units of work that make sense to them. - Supports filtering both within the repository and within GitHub projects (e.g. roadmap and sprint board). @@ -116,6 +127,11 @@ This option involves creating a label for each 30k deliverable with a consistent This option involves creating a single select "deliverable" column in the GitHub projects, with values for each 30k deliverable, and then selecting the corresponding "deliverable" value for each issue added to the project. +> [!TIP] +> **Bottom line:** This is the best option if: +> - we want a consistent way of filtering, grouping, and sorting issues by deliverable in GitHub projects and reporting +> - but can compromise on being able to filter by deliverable in the **repository** + - **Pros** - Allows the engineering team to continue to use GitHub milestones to organize issues into units of work that make sense to them. - Supports filtering within GitHub projects (e.g. roadmap and sprint board). @@ -130,6 +146,9 @@ This option involves creating a single select "deliverable" column in the GitHub This option involves tagging a 30k deliverable from the body of each issue using a reserved phrase (e.g. "30k deliverable: #123"). It would function much like [linking a pull request to an issue][linking pull requests] does in GitHub. +> [!TIP] +> **Bottom line:** Probably not the best option unless we only cared about grouping issues by deliverable in custom reporting. + - **Pros** - Allows the engineering team to continue to use GitHub milestones to organize issues into units of work that make sense to them. - Easy to parse in custom reporting. @@ -148,6 +167,11 @@ This option involves creating a label that indicates when a deliverable should b > [!NOTE] > The code should be configured to accept an arbitrary set of labels as filters, so that if the label changes, we only need to change the top-level configuration and not several lines of the source code. +> [!TIP] +> **Bottom line:** This is the best option if we: +> - want an easy way to explicitly indicate when a deliverable should be included or excluded from reporting +> - and are okay with decoupling the reporting logic from the business logic around deliverable status + - **Pros** - Makes the choice to include a deliverable in a report explicit and easy to understand. - Enables users to add or remove deliverables from reporting without changing the logic or the source code. @@ -163,6 +187,11 @@ This option involves filtering the deliverables that are included in reporting b > [!NOTE] > The code should be configured to accept an arbitrary set of statuses as filters, so that if we want to change which statuses are included, we only need to change the top-level configuration and not several lines of the source code. +> [!TIP] +> **Bottom line:** This is the best option if we: +> - want deliverables to automatically be included in reporting once they enter a specific status (e.g. "in progress") +> - and we don't anticipate edge cases that require including or excluding deliverables from reporting despite their status + - **Pros** - Enables users to add or remove deliverables from reporting without changing the logic or the source code. - Makes it easy to change the logic that determines which statuses are used to include/exclude issues from reporting. @@ -178,6 +207,9 @@ This option involves specifying the deliverables we want to include in the repor > [!NOTE] > The code should be configured to accept an arbitrary list of issue titles or numbers, so that if we want to change which deliverables are included, we only need to change the top-level configuration and not several lines of the source code. +> [!TIP] +> **Bottom line:** This is probably not a good option unless we want to version control when we add or remove deliverables from reporting. + - **Pros** - Makes the choice to include a deliverable in a report explicit and easy to understand. - Prevents someone from accidentally removing a deliverable from reporting by changing a label or status. From 67f826222670083cb330a86d637eac0d7efbfc3b Mon Sep 17 00:00:00 2001 From: widal001 Date: Wed, 20 Dec 2023 18:32:16 -0500 Subject: [PATCH 07/14] feat: Adds recommendation to ADR --- ...23-12-15-deliverable-reporting-strategy.md | 28 ++++++++++++------- 1 file changed, 18 insertions(+), 10 deletions(-) diff --git a/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md b/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md index 353b3e142..26b3bdc8e 100644 --- a/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md +++ b/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md @@ -63,25 +63,33 @@ Our recommended approach to limiting the deliverables that are included in repor ### Assigning issues to deliverables -TODO: Trying to decide between the labels option and the deliverable column option. +We've decided to use a "deliverable" column to assign issues to a parent 30k deliverable. This involves: + +- creating a single select column in both the product roadmap and the sprint board +- populating that column with options that represent each 30k deliverables in our roadmap +- using that column to indicate the 30k deliverable that an issue is assigned to - **Positive outcomes** - - {e.g., improved performance on quality metric, new capability enabled, ...} - - ... + - We can filter, group, and sort issues by deliverable in GitHub projects and GitHub's automated insight reporting. + - The engineering team can continue to use GitHub milestones to organize issues into units of work that are smaller than a 30k deliverable. - **Negative outcomes** - - {e.g., decreased performance on quality metric, risk, follow-up decisions required, ...} - - ... + - We won't be able to filter for issues assigned to a given 30k deliverable within the GitHub repository. + - We'll have to make sure the list of options in the deliverable column is consistent across GitHub projects in order to join issues from different projects correctly in our custom reporting. + - We'll have to update the current logic in our custom reporting so that issues are joined to their parent deliverable using the value of this column. + +> [!NOTE] +> If the team finds a consistent need to filter the list of issues by deliverable within the repository, we may revisit this decision and choose to use ***both*** a label and a deliverable column to assign an issue to a 30k deliverable. We've decided **not** to use both options for the time being to avoid having multiple (potentially conflicting) ways of assigning an issue to a given deliverable. ### Limiting the 30k deliverables included in reporting -TODO: Trying to decide between the label option and the status option. +We've decided to use the status of the deliverable in the product roadmap board to determine when deliverables are included or excluded from reporting. - **Positive outcomes** - - {e.g., improved performance on quality metric, new capability enabled, ...} - - ... + - Keeps our reporting strategy closed aligned with how we're monitoring our delivery progress. + - Avoids creating *another* field or label that needs to be maintained separately. - **Negative outcomes** - - {e.g., decreased performance on quality metric, risk, follow-up decisions required, ...} - - ... + - Tightly couples reporting logic with delivery management, which may introduce challenges if there are instances in which we want to report on some but not all deliverables in a given status. + - If stakeholders aren't familiar with the relationship between deliverable status and reporting, it may be harder for them to understand why certain deliverables appear in a given report but others do not. ## Evaluation - Assigning issues to deliverables From 37e3a1186457130b19343274391c96ce5b2ab1f7 Mon Sep 17 00:00:00 2001 From: widal001 Date: Fri, 5 Jan 2024 09:58:03 -0500 Subject: [PATCH 08/14] feat: Adds option for creating milestones per 10k This option most closely reflects the current strategy for reporting --- ...23-12-15-deliverable-reporting-strategy.md | 20 +++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md b/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md index 26b3bdc8e..17423db06 100644 --- a/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md +++ b/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md @@ -48,7 +48,8 @@ Our recommended approach to limiting the deliverables that are included in repor ### Assigning issues to deliverables -- **Milestones:** Add the issue to a milestone that represents a 30k deliverable +- **Milestones per 10k:** Add the issue to a milestone that represents a 10k deliverable and tag the 30k deliverable in the body of the milestone +- **Milestones per 30k:** Add the issue to a milestone that represents a 30k deliverable - **Labels:** Tag the issue with a label that represents a 30k deliverable - **Deliverable column:** Add a custom "deliverable" column to the GitHub projects with values representing each 30k deliverable - **Reserved phrase:** Use a reserved phrase to tag a 30k deliverable in the body of the issue @@ -93,7 +94,22 @@ We've decided to use the status of the deliverable in the product roadmap board ## Evaluation - Assigning issues to deliverables -### Milestone +### Milestones per 10k deliverable + +This option involves creating GitHub milestones that loosely map to the 10k deliverables under a given 30k deliverable. Each milestone then uses a key phrase `maps to 30k ft deliverable: #{issue number}` to indicate which 30k deliverable it rolls up to, and each issue assigned to that milestone is counted toward the 30k deliverable that is tagged. + +> [!TIP] +> **Bottom line:** This option works for custom reporting, but is probably not the best option moving forward because it doesn't allow us to easily group, search, and filter issues by 30k deliverable in GitHub projects or reporting. + +- **Pros** + - Most closely aligns with our current strategy for assigning issues to 30k deliverables. + - Only requires users to associate milestones to 30k deliverables, instead of each individual issue. +- **Cons** + - Does not support filtering or searching by 30k deliverable within the GitHub repository. + - Does not support filtering or searching by 30k deliverable within GitHub projects (e.g. roadmap or sprint board). + - Does not support grouping by 30k deliverable within GitHub projects or GitHub insight reporting. + +### Milestone per 30k deliverable This option involves creating a milestone for each 30k deliverable and assigning issues to that milestone if they are required for delivery of that 30k. From 4ecc6ff4d7c1a2c549a3b70d92019c8d4e852733 Mon Sep 17 00:00:00 2001 From: widal001 Date: Fri, 5 Jan 2024 10:00:05 -0500 Subject: [PATCH 09/14] feat: Adds some other cons to the reporting options - Impact of deleting old deliverable column values and deliverable labels - The maintenance cost of assigning a value to a field on an issue --- .../adr/2023-12-15-deliverable-reporting-strategy.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md b/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md index 17423db06..afc5e53b4 100644 --- a/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md +++ b/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md @@ -73,8 +73,10 @@ We've decided to use a "deliverable" column to assign issues to a parent 30k del - **Positive outcomes** - We can filter, group, and sort issues by deliverable in GitHub projects and GitHub's automated insight reporting. - The engineering team can continue to use GitHub milestones to organize issues into units of work that are smaller than a 30k deliverable. + - The logic for grouping issues by deliverable will be consistent between GitHub insight reports and our custom-built reports. - **Negative outcomes** - We won't be able to filter for issues assigned to a given 30k deliverable within the GitHub repository. + - Updating a field on a project can be done from the issue page itself, but the issue first needs to be added to the project before the field is updated. This requires an extra step compared to assigning a label or milestone. - We'll have to make sure the list of options in the deliverable column is consistent across GitHub projects in order to join issues from different projects correctly in our custom reporting. - We'll have to update the current logic in our custom reporting so that issues are joined to their parent deliverable using the value of this column. @@ -145,7 +147,7 @@ This option involves creating a label for each 30k deliverable with a consistent - Supports filtering both within the repository and within GitHub projects (e.g. roadmap and sprint board). - **Cons** - Does not easily support grouping in GitHub projects or GitHub insights reporting. - - Will result in a large number of labels if 30k labels aren't deleted once a 30k deliverable is complete. + - Will result in a large number of labels if 30k labels aren't deleted once a 30k deliverable is complete. And if we delete old deliverable labels, it will impact our ability to report on past deliverables. ### Deliverable column @@ -163,7 +165,7 @@ This option involves creating a single select "deliverable" column in the GitHub - Supports customizing the order of groups on the sprint board when grouping by deliverable -- for example we can make "Static site public launch" appear above "GET Opportunities" even though GET opportunities would be first alphabetically. - **Cons** - Does not support filtering or searching within the GitHub repository. - - Will result in a large number of values for the deliverable column if not regularly maintained. + - Will result in a large number of values for the deliverable column if not regularly maintained. And if we delete old deliverable values it will impact our ability to report on past deliverables. - List of deliverable column values will have to be maintained separately across projects -- inconsistencies between these lists may introduce bugs in custom reporting. ### Reserved phrase From 5831bfabf360fca818dc281ddd31129b6152a7bd Mon Sep 17 00:00:00 2001 From: widal001 Date: Fri, 5 Jan 2024 10:12:38 -0500 Subject: [PATCH 10/14] fix: Incorporates PR comments - Notes importance of keeping 30ks and milestones aligned - Notes cases where we can set up a linter to validate consistency - Expands on pro of using statuses for reporting --- .../adr/2023-12-15-deliverable-reporting-strategy.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md b/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md index afc5e53b4..04fcbc984 100644 --- a/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md +++ b/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md @@ -72,7 +72,7 @@ We've decided to use a "deliverable" column to assign issues to a parent 30k del - **Positive outcomes** - We can filter, group, and sort issues by deliverable in GitHub projects and GitHub's automated insight reporting. - - The engineering team can continue to use GitHub milestones to organize issues into units of work that are smaller than a 30k deliverable. + - The engineering team can continue to use GitHub milestones to organize issues into units of work that are smaller than a 30k deliverable. **Note:** While enabling the engineering team to use milestones to organize issues into smaller units of work, we want to avoid situations in which a given milestone contains issues from multiple 30k deliverables -- we can enforce this with a linter as well as a view in the GitHub project. - The logic for grouping issues by deliverable will be consistent between GitHub insight reports and our custom-built reports. - **Negative outcomes** - We won't be able to filter for issues assigned to a given 30k deliverable within the GitHub repository. @@ -166,7 +166,7 @@ This option involves creating a single select "deliverable" column in the GitHub - **Cons** - Does not support filtering or searching within the GitHub repository. - Will result in a large number of values for the deliverable column if not regularly maintained. And if we delete old deliverable values it will impact our ability to report on past deliverables. - - List of deliverable column values will have to be maintained separately across projects -- inconsistencies between these lists may introduce bugs in custom reporting. + - List of deliverable column values will have to be maintained separately across projects -- inconsistencies between these lists may introduce bugs in custom reporting. Though we could address this by creating a linter and the discrepancy would be easy to notice the next time the report is run. ### Reserved phrase @@ -221,7 +221,7 @@ This option involves filtering the deliverables that are included in reporting b - **Pros** - Enables users to add or remove deliverables from reporting without changing the logic or the source code. - Makes it easy to change the logic that determines which statuses are used to include/exclude issues from reporting. - - Keeps the reporting and delivery management in sync. + - Keeps the reporting and delivery management aligned by automatically updating our reports to reflect the deliverables we're currently working on. - **Cons** - Logic behind which deliverables are included in reporting is not as explicit as having a dedicated label. - Requires the reporting logic to be tightly coupled with the rules for assigning deliverable status. From e21130f9b175611f0ea77576b2794391146b35b9 Mon Sep 17 00:00:00 2001 From: widal001 Date: Fri, 5 Jan 2024 11:29:52 -0500 Subject: [PATCH 11/14] feat: Adds steps and examples to reporting ADR --- ...23-12-15-deliverable-reporting-strategy.md | 82 ++++++++++++++++++- 1 file changed, 79 insertions(+), 3 deletions(-) diff --git a/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md b/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md index 04fcbc984..dfd028815 100644 --- a/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md +++ b/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md @@ -103,6 +103,24 @@ This option involves creating GitHub milestones that loosely map to the 10k deli > [!TIP] > **Bottom line:** This option works for custom reporting, but is probably not the best option moving forward because it doesn't allow us to easily group, search, and filter issues by 30k deliverable in GitHub projects or reporting. +#### Examples + +- Milestone mapped to 10k deliverable +- Issue assigned to this milestone + +#### Steps to create a 30k deliverable and assign an issue to it + +1. Create a 30k deliverable issue +2. Create a milestone that corresponds to a 10k deliverable. +3. Tag the number of the 30k deliverable it rolls up to in the body of the milestone using the phrase "Maps to 30k ft deliverable: #{issue number}" +4. Create an issue representing a task that is required for a given 30k deliverable +5. Assign that issue to the same milestone + +#### Steps to rename a 30k deliverable + +1. Rename the 30k deliverable issue +2. Rename the milestone that corresponds to the 30k deliverable + - **Pros** - Most closely aligns with our current strategy for assigning issues to 30k deliverables. - Only requires users to associate milestones to 30k deliverables, instead of each individual issue. @@ -115,14 +133,27 @@ This option involves creating GitHub milestones that loosely map to the 10k deli This option involves creating a milestone for each 30k deliverable and assigning issues to that milestone if they are required for delivery of that 30k. -> [!NOTE] -> This is a slightly different use of milestones than the project currently supports. Right now, the engineering team can create multiple milestones for a given 30k deliverable and reporting is driven by tagging the parent 30k deliverable in the description of the milestone. This new approach would require a *single* milestone per 30k deliverable and all tickets associated with that deliverable would need to be added to the milestone to be included in reporting. - > [!TIP] > **Bottom line:** This is the best option if we: > - want a consistent way to filter and group issues by deliverable across all GitHub projects and reporting as well as within the repository > - but are okay with preventing the engineering team from using milestones to organize issues into smaller units of work +#### Examples + +- Milestone mapped to 30k deliverable +- Issue assigned to this milestone +- Searching for issues with this milestone in the repo +- Searching for issues with this milestone in the GitHub project +- Grouping issues by milestone in the GitHub project +- Grouping issues by milestone in GitHub insight reporting + +#### Steps to create a 30k deliverable and assign an issue to it + +1. Create a 30k deliverable issue +2. Create a milestone that corresponds to this 30k deliverable +3. Assign the 30k deliverable issue to that milestone +4. Create an issue representing a task that is required for a given 30k deliverable +5. Assign that issue to the same milestone - **Pros** - Ensures that there is just one source of truth for the list of issues associated with a given 30k deliverable. @@ -142,6 +173,21 @@ This option involves creating a label for each 30k deliverable with a consistent > - we want a consistent way to filter issues by deliverable in the repository and across GitHub projects > - but can compromise on being able to **group** by deliverable in GitHub projects or reporting +#### Examples + +- Issue with this label +- Searching for issues with this label in the repo +- Searching for issues with this label in the GitHub project +- Attempting to group by label in GitHub insight reporting + +#### Steps to create a 30k deliverable and assign an issue to it + +1. Create a 30k deliverable issue +2. Create a label that represents this 30k deliverable +3. Apply that label to the 30k deliverable issue +4. Create an issue representing a task that is required for a given 30k deliverable +5. Apply that label to the task-level issue + - **Pros** - Allows the engineering team to continue to use GitHub milestones to organize issues into units of work that make sense to them. - Supports filtering both within the repository and within GitHub projects (e.g. roadmap and sprint board). @@ -158,6 +204,23 @@ This option involves creating a single select "deliverable" column in the GitHub > - we want a consistent way of filtering, grouping, and sorting issues by deliverable in GitHub projects and reporting > - but can compromise on being able to filter by deliverable in the **repository** +#### Examples + +- Issue with this deliverable value +- Searching for issues with this deliverable in the GitHub project +- Grouping issues by deliverable in GitHub project +- Grouping issues by deliverable in GitHub insight reporting + +#### Steps to create a 30k deliverable and assign an issue to it + +1. Create a 30k deliverable issue +2. Add a new value for this 30k deliverable to the deliverable columns in: + - The product roadmap GitHub project + - The sprint planning GitHub project +3. Choose that deliverable value for the 30k deliverable issue in the product roadmap +4. Create an issue representing a task that is required for a given 30k deliverable +5. Choose that deliverable value for the task-level issue in the product roadmap + - **Pros** - Allows the engineering team to continue to use GitHub milestones to organize issues into units of work that make sense to them. - Supports filtering within GitHub projects (e.g. roadmap and sprint board). @@ -175,6 +238,19 @@ This option involves tagging a 30k deliverable from the body of each issue using > [!TIP] > **Bottom line:** Probably not the best option unless we only cared about grouping issues by deliverable in custom reporting. +#### Examples + +- Issue with this deliverable value +- Searching for issues with this deliverable in the GitHub project +- Grouping issues by deliverable in GitHub project +- Grouping issues by deliverable in GitHub insight reporting + +#### Steps to create a 30k deliverable and assign an issue to it + +1. Create a 30k deliverable issue +2. Create an issue representing a task that is required for a given 30k deliverable +3. Tag that 30k deliverable in the body of the task using a reserved phrase + - **Pros** - Allows the engineering team to continue to use GitHub milestones to organize issues into units of work that make sense to them. - Easy to parse in custom reporting. From ae880e047deedc5f5cf014b99a67a20b753eb392 Mon Sep 17 00:00:00 2001 From: widal001 Date: Fri, 5 Jan 2024 15:32:33 -0500 Subject: [PATCH 12/14] feat: Adds comparison table and links to examples --- ...23-12-15-deliverable-reporting-strategy.md | 84 ++++++++++++++----- 1 file changed, 63 insertions(+), 21 deletions(-) diff --git a/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md b/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md index dfd028815..4c088d49b 100644 --- a/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md +++ b/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md @@ -96,6 +96,20 @@ We've decided to use the status of the deliverable in the product roadmap board ## Evaluation - Assigning issues to deliverables +### Comparison matrix + +| Factor | Milestone per 10k | Milestone per 30k | Label | Deliverable column | Reserved phrase | +| ------------------------------------- | :---------------: | :---------------: | :---: | :----------------: | :-------------: | +| Supports filtering in repo | ❌ | ✅ | ✅ | ❌ | ❌ | +| Supports filtering in GH project | ❌ | ✅ | ✅ | ✅ | ❌ | +| Supports grouping in GH project | ❌ | ✅ | ❌ | ✅ | ❌ | +| Supports grouping in GH reporting | ❌ | ✅ | ❌ | ✅ | ❌ | +| Supports custom sorting in GH project | ❌ | ✅ | ❌ | ✅ | ❌ | +| Supports custom reporting | ✅ | ✅ | ✅ | ✅ | ✅ | +| Enables engineers to organize issues | ✅ | ❌ | ✅ | ✅ | ✅ | +| # of steps to create a deliverable | 5 | 5 | 5 | 6 | 3 | +| # of steps to rename a deliverable | 1 | 2 | 2 | 3 | 1 | + ### Milestones per 10k deliverable This option involves creating GitHub milestones that loosely map to the 10k deliverables under a given 30k deliverable. Each milestone then uses a key phrase `maps to 30k ft deliverable: #{issue number}` to indicate which 30k deliverable it rolls up to, and each issue assigned to that milestone is counted toward the 30k deliverable that is tagged. @@ -105,8 +119,8 @@ This option involves creating GitHub milestones that loosely map to the 10k deli #### Examples -- Milestone mapped to 10k deliverable -- Issue assigned to this milestone +- [Milestone mapped to 10k deliverable](https://github.com/widal001/project-demo/milestone/11) +- [Issue assigned to this milestone](https://github.com/widal001/project-demo/issues/59) (see milestone section on the right side) #### Steps to create a 30k deliverable and assign an issue to it @@ -119,7 +133,8 @@ This option involves creating GitHub milestones that loosely map to the 10k deli #### Steps to rename a 30k deliverable 1. Rename the 30k deliverable issue -2. Rename the milestone that corresponds to the 30k deliverable + +#### Pros and cons - **Pros** - Most closely aligns with our current strategy for assigning issues to 30k deliverables. @@ -140,12 +155,12 @@ This option involves creating a milestone for each 30k deliverable and assigning #### Examples -- Milestone mapped to 30k deliverable -- Issue assigned to this milestone -- Searching for issues with this milestone in the repo -- Searching for issues with this milestone in the GitHub project -- Grouping issues by milestone in the GitHub project -- Grouping issues by milestone in GitHub insight reporting +- [Milestone mapped to 30k deliverable](https://github.com/widal001/project-demo/milestone/10) +- [Issue assigned to this milestone](https://github.com/widal001/project-demo/issues/70) +- [Searching for issues with this milestone in the repo](https://github.com/widal001/project-demo/issues?q=is%3Aopen+is%3Aissue+milestone%3A%22API+soft+launch%22) +- [Searching for issues with this milestone in the GitHub project](https://github.com/users/widal001/projects/3/views/1?filterQuery=milestone%3A%22API+soft+launch%22) +- [Grouping issues by milestone in the GitHub project](https://github.com/users/widal001/projects/3/views/6) +- [Grouping issues by milestone in GitHub insight reporting](https://github.com/users/widal001/projects/3/insights/3) #### Steps to create a 30k deliverable and assign an issue to it @@ -155,6 +170,13 @@ This option involves creating a milestone for each 30k deliverable and assigning 4. Create an issue representing a task that is required for a given 30k deliverable 5. Assign that issue to the same milestone +#### Steps to rename a 30k deliverable + +1. Rename the 30k deliverable issue +2. Rename the milestone that corresponds to the 30k deliverable + +#### Pros and cons + - **Pros** - Ensures that there is just one source of truth for the list of issues associated with a given 30k deliverable. - Supports filtering both within the repository and within GitHub projects (e.g. roadmap and sprint board). @@ -175,10 +197,10 @@ This option involves creating a label for each 30k deliverable with a consistent #### Examples -- Issue with this label -- Searching for issues with this label in the repo -- Searching for issues with this label in the GitHub project -- Attempting to group by label in GitHub insight reporting +- [Issue with this label](https://github.com/widal001/project-demo/issues/75) +- [Searching for issues with this label in the repo](https://github.com/widal001/project-demo/issues?q=is%3Aissue+is%3Aopen+label%3A%2230k%3A+API+soft+launch%22) +- [Searching for issues with this label in the GitHub project](https://github.com/users/widal001/projects/3/views/1?filterQuery=label%3A%2230k%3A+API+soft+launch%22) +- [Attempting to group by label in GitHub insight reporting](https://github.com/users/widal001/projects/3/insights/5) #### Steps to create a 30k deliverable and assign an issue to it @@ -188,6 +210,13 @@ This option involves creating a label for each 30k deliverable with a consistent 4. Create an issue representing a task that is required for a given 30k deliverable 5. Apply that label to the task-level issue +#### Steps to rename a 30k deliverable + +1. Rename the 30k deliverable issue +2. Rename the label that corresponds to the 30k deliverable + +#### Pros and cons + - **Pros** - Allows the engineering team to continue to use GitHub milestones to organize issues into units of work that make sense to them. - Supports filtering both within the repository and within GitHub projects (e.g. roadmap and sprint board). @@ -206,10 +235,11 @@ This option involves creating a single select "deliverable" column in the GitHub #### Examples -- Issue with this deliverable value -- Searching for issues with this deliverable in the GitHub project -- Grouping issues by deliverable in GitHub project -- Grouping issues by deliverable in GitHub insight reporting +- [Issue with this deliverable value](https://github.com/widal001/project-demo/issues/65) (Click to expand the down arrow to expand the "Demo sprint board" project details) +- [Searching for issues with this deliverable in the GitHub project](https://github.com/users/widal001/projects/3/views/1?filterQuery=deliverable%3A%22Static+site+launch%22) +- [Grouping issues by deliverable in GitHub project](https://github.com/users/widal001/projects/3/views/7) +- [Grouping issues by deliverable in GitHub insight reporting](https://github.com/users/widal001/projects/3/insights/2) +- [Slicing by deliverable and grouping by milestone](https://github.com/users/widal001/projects/3/views/8?sliceBy%5Bvalue%5D=Open+source+group+kickoff) #### Steps to create a 30k deliverable and assign an issue to it @@ -221,6 +251,15 @@ This option involves creating a single select "deliverable" column in the GitHub 4. Create an issue representing a task that is required for a given 30k deliverable 5. Choose that deliverable value for the task-level issue in the product roadmap +#### Steps to rename a 30k deliverable + +1. Rename the 30k deliverable issue +2. Rename the deliverable value that corresponds to the 30k deliverable in: + - The product roadmap GitHub project + - The sprint planning GitHub project + +#### Pros and cons + - **Pros** - Allows the engineering team to continue to use GitHub milestones to organize issues into units of work that make sense to them. - Supports filtering within GitHub projects (e.g. roadmap and sprint board). @@ -240,10 +279,7 @@ This option involves tagging a 30k deliverable from the body of each issue using #### Examples -- Issue with this deliverable value -- Searching for issues with this deliverable in the GitHub project -- Grouping issues by deliverable in GitHub project -- Grouping issues by deliverable in GitHub insight reporting +- [Issue with reserved phrase](https://github.com/widal001/project-demo/issues/73) #### Steps to create a 30k deliverable and assign an issue to it @@ -251,6 +287,12 @@ This option involves tagging a 30k deliverable from the body of each issue using 2. Create an issue representing a task that is required for a given 30k deliverable 3. Tag that 30k deliverable in the body of the task using a reserved phrase +#### Steps to rename a 30k deliverable + +1. Rename the 30k deliverable issue + +#### Pros and cons + - **Pros** - Allows the engineering team to continue to use GitHub milestones to organize issues into units of work that make sense to them. - Easy to parse in custom reporting. From 6808467142c0700f7f8aeab060ecf17806626562 Mon Sep 17 00:00:00 2001 From: Billy Daly Date: Tue, 16 Jan 2024 11:54:14 -0500 Subject: [PATCH 13/14] fix: Incorporates feedback from PR review Commits suggested changes from Sumi and Andy Co-authored-by: Andy Cochran Co-authored-by: Sumi <111455374+sumiat@users.noreply.github.com> --- .../adr/2023-12-15-deliverable-reporting-strategy.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md b/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md index 4c088d49b..48e8f420d 100644 --- a/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md +++ b/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md @@ -41,7 +41,7 @@ Our recommended strategy for assigning issues to a given 30k deliverable should Our recommended approach to limiting the deliverables that are included in reporting should consider the following criteria: - The logic for including a 30k deliverable in reporting should be clear and easy to understand -- Users should be able to add or remove a given 30k deliverable from reports without having to change the underlying logic +- Users should be able to add or remove a given 30k deliverable from reports without having to change the underlying report logic or make changes to individual GitHub Issues - If necessary, users should be able to change the reporting logic without rewriting significant sections of the source code ## Options considered @@ -76,9 +76,10 @@ We've decided to use a "deliverable" column to assign issues to a parent 30k del - The logic for grouping issues by deliverable will be consistent between GitHub insight reports and our custom-built reports. - **Negative outcomes** - We won't be able to filter for issues assigned to a given 30k deliverable within the GitHub repository. - - Updating a field on a project can be done from the issue page itself, but the issue first needs to be added to the project before the field is updated. This requires an extra step compared to assigning a label or milestone. + - Updating a field on a project can be done from the issue page itself, but the issue first needs to be added to the project before the field is updated. This requires an extra step compared to assigning a label or milestone, making it more prone to be skipped. - We'll have to make sure the list of options in the deliverable column is consistent across GitHub projects in order to join issues from different projects correctly in our custom reporting. - We'll have to update the current logic in our custom reporting so that issues are joined to their parent deliverable using the value of this column. +- 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. > [!NOTE] > If the team finds a consistent need to filter the list of issues by deliverable within the repository, we may revisit this decision and choose to use ***both*** a label and a deliverable column to assign an issue to a 30k deliverable. We've decided **not** to use both options for the time being to avoid having multiple (potentially conflicting) ways of assigning an issue to a given deliverable. From 1b876b404c9d8846ca37639728ce690b5b4bc4d7 Mon Sep 17 00:00:00 2001 From: Billy Daly Date: Tue, 16 Jan 2024 11:57:32 -0500 Subject: [PATCH 14/14] fix: Typo in reporting strategy ADR --- .../decisions/adr/2023-12-15-deliverable-reporting-strategy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md b/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md index 48e8f420d..30e8f07f3 100644 --- a/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md +++ b/documentation/decisions/adr/2023-12-15-deliverable-reporting-strategy.md @@ -79,7 +79,7 @@ We've decided to use a "deliverable" column to assign issues to a parent 30k del - Updating a field on a project can be done from the issue page itself, but the issue first needs to be added to the project before the field is updated. This requires an extra step compared to assigning a label or milestone, making it more prone to be skipped. - We'll have to make sure the list of options in the deliverable column is consistent across GitHub projects in order to join issues from different projects correctly in our custom reporting. - We'll have to update the current logic in our custom reporting so that issues are joined to their parent deliverable using the value of this column. -- 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. + - 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. > [!NOTE] > If the team finds a consistent need to filter the list of issues by deliverable within the repository, we may revisit this decision and choose to use ***both*** a label and a deliverable column to assign an issue to a 30k deliverable. We've decided **not** to use both options for the time being to avoid having multiple (potentially conflicting) ways of assigning an issue to a given deliverable.