mirror of
https://github.com/IRS-Public/direct-file.git
synced 2025-06-28 15:27:41 +00:00
Fix spelling typos and markdown warnings
Just some minor fixes. Nothing special Signed-off-by: Tim Smith <tsmith84@gmail.com>
This commit is contained in:
Tim Smith
parent
e0d5c84451
commit
25d0baefa0
39 changed files with 174 additions and 170 deletions
|
|
@ -55,7 +55,7 @@ The first step is to identify whether the work is destined for the current `prod
|
|||
1. Create a PR for changes into `production` branch
|
||||
1. Squash and merge PR into `production` branch
|
||||
1. Create a second PR from the `production` branch into `main` and resolve conflicts if needed. We are unable to automate this step at this time, but would like to merge into `main` on every PR in order to make the conflict resolution easier.
|
||||
- Note: Regular merge (not "Squash and Merge") is recommended here
|
||||
- Note: Regular merge (not "Squash and Merge") is recommended here
|
||||
|
||||
##### For future features
|
||||
1. Check out `main` branch
|
||||
|
|
@ -81,7 +81,7 @@ The first step is to identify whether the work is destined for the current `prod
|
|||
#### Releases and Deployment
|
||||
- Cut releases from `main`
|
||||
- Deploy from `main`
|
||||
- Reserve a lower environment for regular dpeloyments from `future` for testing future features
|
||||
- Reserve a lower environment for regular deployments from `future` for testing future features
|
||||
- Continue these two branches throughout the year
|
||||
- When it is time to cutover to TY25 (December 2025 or January 2026), fork a new `main` branch from `future` and continue the same processes for the next tax year
|
||||
|
||||
|
|
@ -94,7 +94,7 @@ The first step is to identify whether the work is destined for the current `prod
|
|||
1. Make PR against `main` branch
|
||||
1. Merge into `main` branch
|
||||
1. Create a second PR from the `main` branch into `future` and resolve conflicts if needed. We are unable to automate this step at this time, but would like to merge into `main` on every PR in order to make the conflict resolution easier.
|
||||
- Note: Regular merge (not "Squash and Merge") is recommended here
|
||||
- Note: Regular merge (not "Squash and Merge") is recommended here
|
||||
|
||||
##### For future features
|
||||
1. Check out `future` branch
|
||||
|
|
|
|||
|
|
@ -6,16 +6,16 @@ Written: 20Jun2023
|
|||
CSS has some major problems. Namely, it:
|
||||
1. lacks variable names and the ability to import variables from other libraries.
|
||||
1. lacks nesting and other hierarchical structures that are common in components.
|
||||
1. is global (cascading!), leading to naming conflicts, difficult dead code detection, and difficult maintainbility in large code bases.
|
||||
1. is global (cascading!), leading to naming conflicts, difficult dead code detection, and difficult maintainability in large code bases.
|
||||
1. is constantly updated, and can have different implementations and minor differences between different browsers
|
||||
|
||||
To avoid these issues, while adding additional features, most of the web development community uses one or more forms of CSS Preprocessor, preprocessing a superset of CSS into the CSS that will eventually reach the users' browsers.
|
||||
To avoid these issues, while adding additional features, most of the web development community uses one or more forms of CSS Preprocessor, preprocessing a superset of CSS into the CSS that will eventually reach the users' browsers.
|
||||
|
||||
### Required Features
|
||||
1. Must be able to implement and rely on the US Web Design System (USWDS)
|
||||
1. Specifically, we need to interact with and rely on https://github.com/trussworks/react-uswds and https://github.com/uswds/uswds. Both of these systems use SASS and export SASS variables.
|
||||
1. Must be able to scope CSS, eliminating global classes
|
||||
1. Must help, not hinder, building an accessible product.
|
||||
1. Must help, not hinder, building an accessible product.
|
||||
1. Must build output that runs without issue on popular phones and computers
|
||||
1. Must support mobile development and responsive design
|
||||
|
||||
|
|
@ -26,19 +26,19 @@ To avoid these issues, while adding additional features, most of the web develop
|
|||
|
||||
## OSS Landscape
|
||||
There are a few CSS popular preprocessors:
|
||||
1. [SASS](https://sass-lang.com/), per their own marketing speak, defines themselves as "the most mature, stable, and powerful professional grade CSS extension language in the world." Sass has ~10m weekly downloads on NPM and is increasing in number of downloads.
|
||||
1. [LESS](https://lesscss.org/) is the main competitor to SASS, and contains many of the same features. Less has ~4m weekly downloads on NPM and is flat in number of downloads.
|
||||
1. [PostCSS](https://postcss.org/) converts modern css into something most browsers can understand, placing polyfills in place. PostCSS is not a separate languagea -- it's a compile step like babel for greater compatibility. Stylelint and other tools are built on PostCSS
|
||||
1. [CSS Modules](https://github.com/css-modules/css-modules) provide local scoping for CSS. Styles are defined in a normal css/less/sass file, then are imported into the React components that use those classes.
|
||||
1. [Tailwind](https://tailwindcss.com/) is noteable for being slightly different than other popular CSS frameworks, and is a css framework -- rather than a preprocessor -- that encourages stylistic, rather than semanetic, classnames directly in markup. It's gaining popularity rapidly (4.7m downloads/wk, up from 3m downloads/wk a year ago). However, it would be hard to integrate with USWDS.
|
||||
1. [SASS](https://sass-lang.com/), per their own marketing speak, defines themselves as "the most mature, stable, and powerful professional grade CSS extension language in the world." Sass has ~10m weekly downloads on NPM and is increasing in number of downloads.
|
||||
1. [LESS](https://lesscss.org/) is the main competitor to SASS, and contains many of the same features. Less has ~4m weekly downloads on NPM and is flat in number of downloads.
|
||||
1. [PostCSS](https://postcss.org/) converts modern css into something most browsers can understand, placing polyfills in place. PostCSS is not a separate language -- it's a compile step like babel for greater compatibility. Stylelint and other tools are built on PostCSS
|
||||
1. [CSS Modules](https://github.com/css-modules/css-modules) provide local scoping for CSS. Styles are defined in a normal css/less/sass file, then are imported into the React components that use those classes.
|
||||
1. [Tailwind](https://tailwindcss.com/) is notable for being slightly different than other popular CSS frameworks, and is a css framework -- rather than a preprocessor -- that encourages stylistic, rather than semantic, classnames directly in markup. It's gaining popularity rapidly (4.7m downloads/wk, up from 3m downloads/wk a year ago). However, it would be hard to integrate with USWDS.
|
||||
1. [Stylelint](https://stylelint.io/) is a CSS linter used to prevent bugs and increase maintainability of CSS
|
||||
|
||||
|
||||
## Decision
|
||||
We should run the following CSS Preprocessors:
|
||||
1. Our CSS Language should be SASS, given its popularity and interoperability with USWDS. Most critically, we can import variable names from USWDS.
|
||||
1. We should additionally use SASS Modules to scope our CSS to their components, avoiding global cascades.
|
||||
1. We should use stylelint with its recommended config. We should also use the [a11y](https://www.npmjs.com/package/@ronilaukkarinen/stylelint-a11y) plugin experimentally to see if it helps us with accesibility (though noting that it seems not well supported and we should be willing to drop it).
|
||||
1. Our CSS Language should be SASS, given its popularity and interoperability with USWDS. Most critically, we can import variable names from USWDS.
|
||||
1. We should additionally use SASS Modules to scope our CSS to their components, avoiding global cascades.
|
||||
1. We should use stylelint with its recommended config. We should also use the [a11y](https://www.npmjs.com/package/@ronilaukkarinen/stylelint-a11y) plugin experimentally to see if it helps us with accessibility (though noting that it seems not well supported and we should be willing to drop it).
|
||||
1. Following our SASS compilation step, we should run postcss to get down to a supported list of browsers that we support via [browserlist](https://github.com/browserslist/browserslist#readme)
|
||||
|
||||
Unsurprisingly, when developing for these criteria (and with a sigh of relief that USWDS uses SASS), this is the same CSS stack used by [Create React App](https://create-react-app.dev/docs/adding-a-css-modules-stylesheet).
|
||||
Unsurprisingly, when developing for these criteria (and with a sigh of relief that USWDS uses SASS), this is the same CSS stack used by [Create React App](https://create-react-app.dev/docs/adding-a-css-modules-stylesheet).
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@
|
|||
## Context and Problem Statement
|
||||
|
||||
[//]: # ([Describe the context and problem statement, e.g., in free form using two to three sentences. You may want to articulate the problem in form of a question.])
|
||||
A decision was made in [adr-screener-config](./adr-screener-config.md) to use Astro SSG (static site generator) for the screener application. It was initially used for an MVP, and later replaced with React/Vite. This adr is to document that change and supercede the previous adr.
|
||||
A decision was made in [adr-screener-config](./adr-screener-config.md) to use Astro SSG (static site generator) for the screener application. It was initially used for an MVP, and later replaced with React/Vite. This adr is to document that change and supersede the previous adr.
|
||||
|
||||
## Decision Drivers
|
||||
|
||||
|
|
@ -25,8 +25,8 @@ Chosen option: "React/Vite", because it was consistent with the client app and t
|
|||
|
||||
- More dynamic content is an option
|
||||
- We can easily utilize react-uswds library.
|
||||
- The i18n system is aligned in both the screener and the client app.
|
||||
- Engineers don't need to learn multiple systems and can seemlessly develop between the two apps. Onboarding for new engineers is simplified.
|
||||
- The i18n system is aligned in both the screener and the client app.
|
||||
- Engineers don't need to learn multiple systems and can seamlessly develop between the two apps. Onboarding for new engineers is simplified.
|
||||
|
||||
### Negative Consequences
|
||||
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ informed: "All project technical staff"
|
|||
|
||||
In supporting a critical task for all U.S. residents, Direct File should be accessible. This decision record sets a clear target for this phase of development to meet those accessibility needs, and we expect to exceed that target when feasible.
|
||||
|
||||
The U.S. describes its accessiblity requirements in [Section 508](https://www.section508.gov/) of the Rehabilitation Act. [WCAG](https://www.w3.org/WAI/standards-guidelines/wcag/) provides the same for the internet at large with three levels of compliance (A, AA, AAA), and it has increased in minor versions (2.0, 2.1, 2.2) over the last 15 years. 508 and WCAG have a [very large overlap](https://www.access-board.gov/ict/#E207.2), and all non-overlapping features unique to 508 are either irrelevant to this project (e.g. manual operation and hardware) or out of this repo's scope (e.g. support channels). See the note in "More Information" below for further information.
|
||||
The U.S. describes its accessibility requirements in [Section 508](https://www.section508.gov/) of the Rehabilitation Act. [WCAG](https://www.w3.org/WAI/standards-guidelines/wcag/) provides the same for the internet at large with three levels of compliance (A, AA, AAA), and it has increased in minor versions (2.0, 2.1, 2.2) over the last 15 years. 508 and WCAG have a [very large overlap](https://www.access-board.gov/ict/#E207.2), and all non-overlapping features unique to 508 are either irrelevant to this project (e.g. manual operation and hardware) or out of this repo's scope (e.g. support channels). See the note in "More Information" below for further information.
|
||||
|
||||
Given these equivalencies, all considered options are oriented toward WCAG and achieve 508 compliance.
|
||||
|
||||
|
|
@ -38,7 +38,7 @@ Chosen option: "WCAG 2.2 AA (forward-thinking)", because it ensures we meet our
|
|||
* Good, because it challenges us to maximize WCAG at level AAA
|
||||
* Good, because it sets Direct File up with the latest a11y guidance for years to come
|
||||
* Good, because it doesn't require any more work than WCAG 2.1 AA with our current design
|
||||
* Neutral, because it may require slighly more work than the bare minimum in the future
|
||||
* Neutral, because it may require slightly more work than the bare minimum in the future
|
||||
* Neutral, some automated a11y tools don't yet support 2.2 (as of Oct 2023)
|
||||
|
||||
### Confirmation
|
||||
|
|
@ -65,7 +65,7 @@ This decision to exceed 508 requirements is confirmed by the IRS' 508 Program Of
|
|||
* Good, because it establishes and exceeds 508 compliance
|
||||
* Good, because it is easy to remember the level expected of all elements (i.e. "what needs level A vs AA?")
|
||||
* Good, because it challenges us to maximize WCAG at level AAA
|
||||
* Neutral, because it may require slighly more work than the bare minimum
|
||||
* Neutral, because it may require slightly more work than the bare minimum
|
||||
* Neutral, because it is an outdated version (see "more information" below)
|
||||
|
||||
### WCAG 2.2 AA (forward-thinking)
|
||||
|
|
@ -75,7 +75,7 @@ This decision to exceed 508 requirements is confirmed by the IRS' 508 Program Of
|
|||
* Good, because it challenges us to maximize WCAG at level AAA
|
||||
* Good, because it sets Direct File up with the latest a11y guidance for years to come
|
||||
* Good, because it doesn't require any more work than WCAG 2.1 AA with our current design
|
||||
* Neutral, because it may require slighly more work than the bare minimum in the future
|
||||
* Neutral, because it may require slightly more work than the bare minimum in the future
|
||||
* Neutral, some automated a11y tools don't yet support 2.2 (as of Oct 2023)
|
||||
|
||||
## More Information
|
||||
|
|
|
|||
|
|
@ -1,16 +1,16 @@
|
|||
## Overview
|
||||
|
||||
There are two main scenarios that, as it currently stands, the combination of our incident response (IR) practices and customer support (CS) motion do not support:
|
||||
|
||||
a) A taxpayer hits submit but an XMl validation failure occurs and they cannot submit at all. CS is unavailable (for whatever reason) and they give up attempting to submit with Direct File.
|
||||
b) A taxpayer submits successfully, but an internal error occurs in the Submit application that blocks our ability to send their return to MeF. CS is not involved because, presumbly, the taxpayer never reached out to CS in the first case as they didn't run into any errors when hitting submit.
|
||||
|
||||
Our inability to reach out to taxpayers proactively is primarily due to the fact that CS can only reach out to taxpayer who reach out to them first via eGAIN.
|
||||
Our inability to reach out to taxpayers proactively is primarily due to the fact that CS can only reach out to taxpayer who reach out to them first via eGAIN.
|
||||
|
||||
In the above scenarios, neither taxpayer knows 1) if the issue they ran into has/will be fixed; and 2) if so, that they should resubmit their return. As a result, they are effectively left in the dark and/or knocked out of the filing with Direct File, thereby forcing them to submit elsewhere.
|
||||
|
||||
While our scale to-date (as of 2/26) has shielded us from the pain of these scenarios, or alleviated them altogether, we don't have a clear way to address them at this moment. Further, there is a very high likelihood that these scenarios will occur over the coming weeks and will become especially painful if/when the submission volume scales dramatically faster than our CS capabilities.
|
||||
|
||||
|
||||
## Proposals
|
||||
|
||||
While we cannot change our CS motion to support this, we can enable a better product experience through how we notify taxpayers via email when an error occurs in our system.
|
||||
|
|
@ -21,14 +21,13 @@ We should notify taxpayers via email that there was an error submitting their re
|
|||
### Notify taxpayers when Direct File has deployed a fix that should allow them to resubmit their return
|
||||
We should also notify taxpayers via email that they are able to submit their return when we have deployed a fix into production that addresses the error that blocked them from submitting in the first place.
|
||||
|
||||
|
||||
### Proposed Technical Changes (Rough)
|
||||
|
||||
1. Add two new HTML Templates to capture the two notification scenarios above, e.g. SubmissionErrorTemplate and ErrorResolvedTemplate. The templates should be added to the backend app, such that the ConfirmationService can process it, as well as the actual HTML template in the email app that is sent via email and rendered to the taxpayer
|
||||
2. When an XML validation failure occurs during submission create a `SubmissionEvent` with an `eventType` of `error_xml` and enqueue a message from the backend to the email app to notify the user (naming of the eventType is TBD, might make sense to add a new `message` column and keep the eventType as `error`)
|
||||
3. Update the SQS message sent from submit -> backend (on the submission confirmation queue) to allow for an `error` status. If the ConfirmationService and SendService are properly configured as per #1 above, everything should flow seemlessly. Similar to #2, create a `SubmissionEvent` with an `eventType` of `error_mef` for each submission that failed to submit to MeF (naming of the eventType is TBD, might make sense to add a new `message` column and keep the eventType as `error`)
|
||||
3. Update the SQS message sent from submit -> backend (on the submission confirmation queue) to allow for an `error` status. If the ConfirmationService and SendService are properly configured as per #1 above, everything should flow seamlessly. Similar to #2, create a `SubmissionEvent` with an `eventType` of `error_mef` for each submission that failed to submit to MeF (naming of the eventType is TBD, might make sense to add a new `message` column and keep the eventType as `error`)
|
||||
4. Add a function to the backend that, when called, ingests a CSV of `taxReturnIds`, transforms the list into a SubmissionStatusMessage and calls ConfirmationService.handleStatusChangeEvent
|
||||
5. Once a deploy goes out that fixes the underlying issue, create a CSV with `taxReturnIds` of the affected taxpayers (both those who reached out to CS and those who did not) using Splunk queries
|
||||
6. Send this CSV to IEP and ask 1) their System Admin to run the command specified in #4; or 2)have them upload it to S3 and do something similar to the email allow list such that the function specified in #4 polls S3 and sends emails based off this polling. This second approach would require more state management but would possibly cut out the need for IEP to run commands and maybe obviate the need for a p2 to make this happen.
|
||||
7. Add monitoring in place to observe the emails being sent out accordingly
|
||||
8. [Alternative] We move the 'submitted' email to send only after we receive submission confirmation, not after we pass XML validation
|
||||
8. [Alternative] We move the 'submitted' email to send only after we receive submission confirmation, not after we pass XML validation
|
||||
|
|
|
|||
|
|
@ -1,7 +1,9 @@
|
|||
# Data Import Redux
|
||||
|
||||
Date: 5 Nov 2024
|
||||
|
||||
## Context
|
||||
|
||||
To facilitate the correctness of the frontend data import system, we will use redux to coalesce data from APIs.
|
||||
|
||||
Data Import has many lifetimes that are independent of traditional timeframes from the app. Data fetches get kicked off, data returns later, data gets validated as ready for import all independently of user action.
|
||||
|
|
@ -14,21 +16,21 @@ Data Import will use the Redux Library to make it easier for us to manage changi
|
|||
|
||||
We will write logic in redux to transform data as it comes in so that the frontend knows when to use it.
|
||||
|
||||
|
||||
# Alternatives Considered
|
||||
|
||||
## React Context and Fact Graph
|
||||
|
||||
- Lack of chained actions - because we expect data from different sections (about you, IP PIN, w2) to come in at different times, we need to be able to chain /retry fetches and coalsce them into one structure. Redux makes this much easier than alternatives considered.
|
||||
- Lack of chained actions - because we expect data from different sections (about you, IP PIN, w2) to come in at different times, we need to be able to chain /retry fetches and coalesce them into one structure. Redux makes this much easier than alternatives considered.
|
||||
- Limits blast radius - with data coming in and out while people are on other screens, redux provides much better APIs to avoid rerenders on API calls that are not relevant to the current screen.
|
||||
|
||||
# Other Libraries
|
||||
|
||||
I looked briefly at Recoil, MobX, Zustand and Jotai but they all seemed geared at simpler apps. Some of Data Import's initial features (e.g. knowing if more than a second has elapsed during a request) are much easier to impliment in redux based on my prototyping. Secondly, Redux is so well used that nobody ever got fired for using redux :P
|
||||
I looked briefly at Recoil, MobX, Zustand and Jotai but they all seemed geared at simpler apps. Some of Data Import's initial features (e.g. knowing if more than a second has elapsed during a request) are much easier to implement in redux based on my prototyping. Secondly, Redux is so well used that nobody ever got fired for using redux :P
|
||||
|
||||
# Future Uses
|
||||
|
||||
Redux has a few key advantages over things we have in our codebase right now:
|
||||
|
||||
- Automatically manages the render cycle more efficiently (important as our react tree grows ever larger)
|
||||
- Proven at scale with complex application state
|
||||
- Well known in the industry with a good tooling eco system
|
||||
|
|
|
|||
|
|
@ -14,9 +14,9 @@ Direct File is built using the [U.S. Web Design System](https://designsystem.dig
|
|||
|
||||
# **Taxonomy and Nicknames**
|
||||
|
||||
A list of names we use for elements and concepts.
|
||||
A list of names we use for elements and concepts.
|
||||
|
||||
For Spanish Translation Glossary see Spanish Glossary Folder in Wiki folder.
|
||||
For Spanish Translation Glossary see Spanish Glossary Folder in Wiki folder.
|
||||
|
||||
## **A**
|
||||
|
||||
|
|
@ -336,7 +336,7 @@ superseded by the term "Checklist"
|
|||
|
||||
# **Information Architecture and tax preparation task flow**
|
||||
|
||||
Direct File guides taxpayers through a structured tax preparation task by means of sets of questions. DF is organized according to a hub-and-spoke model, using the Checklist as the hub, with subsections linked directly from there. Subsections operate as short units of work in the larger task and always return the user to the hub to place control over the task in their hands and to regularly ground them in their progress through the larger task.The overall tax preparation task is organized into some high-level notional sections that are numbered on the checklist. Each numbered section is further organized into one or more subsections. Subsections contain the meat of the task: questions and mechanisms for data entry and structures enabling reviews and edits. Direct File has a notion of different subsection types that consist of interactions needed for collecting responses or data from the taxpayer or delivering information. These types are: question, collection, inner collection, assertion, and review.
|
||||
Direct File guides taxpayers through a structured tax preparation task by means of sets of questions. DF is organized according to a hub-and-spoke model, using the Checklist as the hub, with subsections linked directly from there. Subsections operate as short units of work in the larger task and always return the user to the hub to place control over the task in their hands and to regularly ground them in their progress through the larger task.The overall tax preparation task is organized into some high-level notional sections that are numbered on the checklist. Each numbered section is further organized into one or more subsections. Subsections contain the meat of the task: questions and mechanisms for data entry and structures enabling reviews and edits. Direct File has a notion of different subsection types that consist of interactions needed for collecting responses or data from the taxpayer or delivering information. These types are: question, collection, inner collection, assertion, and review.
|
||||
|
||||
Task flow
|
||||
|
||||
|
|
@ -442,7 +442,7 @@ DF uses data views, subsection overview pages, to enable interaction with comple
|
|||
|
||||
# **Organizing terms (internal)**
|
||||
|
||||
Checklist, Section, Subsection, and Hierarchical categories, Data Views
|
||||
Checklist, Section, Subsection, and Hierarchical categories, Data Views
|
||||
|
||||
## **Checklist**
|
||||
|
||||
|
|
@ -466,7 +466,6 @@ Examples of the "start," "continue," and right-caret cues that lead taxpayers th
|
|||
|
||||
<img width="820" alt="Checklist_start_continue" src="https://github.com/user-attachments/assets/f1c639f5-91b2-41e0-af01-36812fa66fa3" />
|
||||
|
||||
|
||||
### **Navigation**
|
||||
|
||||
* Taxpayers will be prompted by a Start button to begin a section or a Continue button if they have saved at least one input in a subsection, left off in their task and then came back to resume work. Those prompts change as the user progresses. They go away (for section titles) or are replaced with a right-caret (for subsection titles) when DF considers the segment has been completed.
|
||||
|
|
@ -537,7 +536,7 @@ Use this structure for subsections that are composed of nothing more than a coll
|
|||
|
||||
C. Inner Collection Subsection (aka Question-Collection Subsection)
|
||||
|
||||
Use this structure for subsections that combine a flow of questions with a subcollection (like the Child and Dependent Care Credit, which both asks a sequence of questions and multiple care providers' info). Note that this hierarchy has three levels of review UI, with a top-level data view for the subsection, a collection below that, and then each item's data view below the collection hub.
|
||||
Use this structure for subsections that combine a flow of questions with a subcollection (like the Child and Dependent Care Credit, which both asks a sequence of questions and multiple care providers' info). Note that this hierarchy has three levels of review UI, with a top-level data view for the subsection, a collection below that, and then each item's data view below the collection hub.
|
||||
|
||||
|
||||
|
||||
|
|
@ -579,7 +578,7 @@ Data views are a navigational screen type that summarize the answers for a parti
|
|||
|
||||
NOTE: for Assertion subsections, the Assertion screen is the data view because there are no other inputs for which we need to provide edit access.
|
||||
|
||||
* Answers on Data views are presented as key-value pairs. There are the content guidelines for how questions and answers should be written in data views.
|
||||
* Answers on Data views are presented as key-value pairs. There are the content guidelines for how questions and answers should be written in data views.
|
||||
|
||||
|
||||
|
||||
|
|
@ -617,7 +616,7 @@ Data View Error Hierarchy
|
|||
|
||||
Common page types found in Direct File.
|
||||
|
||||
Navigational pages: Dashboard, Checklist, Collection hub, Data view, Review and confirm, Account, and Data import.
|
||||
Navigational pages: Dashboard, Checklist, Collection hub, Data view, Review and confirm, Account, and Data import.
|
||||
|
||||
## **Dashboard**
|
||||
|
||||
|
|
@ -635,7 +634,7 @@ In future years, taxpayers might be able to view (or even interact with) previou
|
|||
|
||||
### **Interaction and behavior**
|
||||
|
||||
When a taxpayer signs on to Direct File they will immediately see their dashboard that reads "Welcome to Direct File", provides their email address, and a tax return card. The tax return card is the main component on the dashboard and provides taxpayers with status updates, alerts, tax return ID, summary links, alerts, and next steps. It is also the final card a taxpayer sees once they have submitted tax information through Direct File.
|
||||
When a taxpayer signs on to Direct File they will immediately see their dashboard that reads "Welcome to Direct File", provides their email address, and a tax return card. The tax return card is the main component on the dashboard and provides taxpayers with status updates, alerts, tax return ID, summary links, alerts, and next steps. It is also the final card a taxpayer sees once they have submitted tax information through Direct File.
|
||||
|
||||
#### **Added additional page**
|
||||
|
||||
|
|
@ -665,7 +664,6 @@ Other subsections start with a Collection hub, which allows a taxpayer to report
|
|||
|
||||
|
||||
|
||||
|
||||
These are examples of collection hubs:
|
||||
|
||||
* Family and household
|
||||
|
|
@ -700,7 +698,7 @@ Review and confirm has a similar visual style to Data views. It provides "Review
|
|||
|
||||
Review and confirm errors
|
||||
|
||||
Review and confirm is a section off the Checklist. Its MVP form repeats the checklist and creates value to the user by slowing their task and calling their attention to all remaining errors and warnings before letting them move ahead to signing and submitting. Once all showstoppers are resolved, the TP can confirm and move forward.
|
||||
Review and confirm is a section off the Checklist. Its MVP form repeats the checklist and creates value to the user by slowing their task and calling their attention to all remaining errors and warnings before letting them move ahead to signing and submitting. Once all showstoppers are resolved, the TP can confirm and move forward.
|
||||
|
||||
Everything that comes before the Review and confirm section is the meat of the tax return. Anything that comes after is related to getting the tax return to the IRS one way or another.
|
||||
|
||||
|
|
@ -718,8 +716,8 @@ Account page under the basic header and side menu which helps users identify whe
|
|||
|
||||
**Information found under account:**
|
||||
|
||||
* How to change your email in ID.me
|
||||
* How to reset your draft and delete submitted returns from your account
|
||||
* How to change your email in ID.me
|
||||
* How to reset your draft and delete submitted returns from your account
|
||||
* Sign out
|
||||
|
||||
<img width="882" alt="Account_wiki_2" src="https://github.com/user-attachments/assets/a3991248-5a9c-4cf2-9b43-bedc27562c50" />
|
||||
|
|
@ -742,7 +740,7 @@ Section-level introductions details
|
|||
|
||||
* Must be evergreen content to serve users working forward through the flow or revisiting the page after having progressed past it
|
||||
|
||||
* When a user continues past the section level intro, it will flow into the section's first subsection, but if the user is revisiting the section introduction after having progressed past it, it links back to the checklist; see the checklist pattern
|
||||
* When a user continues past the section level intro, it will flow into the section's first subsection, but if the user is revisiting the section introduction after having progressed past it, it links back to the checklist; see the checklist pattern
|
||||
|
||||
### **About Subsection Introduction screens**
|
||||
|
||||
|
|
@ -764,7 +762,6 @@ The amount of content on these screens varies. We haven't been strict about the
|
|||
|
||||
|
||||
|
||||
|
||||
If there's a lot of information, the intro info could be broken into 2 screens, like for Family and household:
|
||||
|
||||
|
||||
|
|
@ -803,7 +800,7 @@ Question screens have just 1 question or instruction, and then form field(s) to
|
|||
|
||||
In the Direct File pilot, the majority of question screens have just 1 form field, to keep each screen simple and focused. Some screens have multiple related form fields, like for contact information.
|
||||
|
||||
Many of the questions are required.
|
||||
Many of the questions are required.
|
||||
|
||||
### **Design references**
|
||||
|
||||
|
|
@ -964,7 +961,7 @@ The Direct File dashboard contains a federal tax return card, which invites taxp
|
|||
|
||||
Post-submission tax return statuses are: Submitted, Accepted, Rejected, and resubmitted after rejection. Status alerts are always in bold.
|
||||
|
||||
#### **Submitted**
|
||||
#### **Submitted**
|
||||
|
||||
Submitted returns will see a tax return card with a blue submitted status alert and offers a link to Tax return details page, submitted downloadable PDF, and next steps with details on payment/refund methods. Taxpayers that must file state taxes will see guidance on filing state taxes.
|
||||
|
||||
|
|
@ -1017,11 +1014,11 @@ It's not realistic to ask taxpayers about every tax situation we don't support.
|
|||
|
||||
In the Direct File pilot, there's not 1 set pattern for displaying scope flags. There's currently 3 flavors:
|
||||
|
||||
* Appear inside snacks, for less common scenarios—Seen in You and your family and Deductions. These snack modals aren't focused on scope, but mention an out-of-scope scenario at some point. Often the snack topics are sensitive or rare (ish), and go into extra detail that most TPs won't need.
|
||||
* Appear inside snacks, for less common scenarios—Seen in You and your family and Deductions. These snack modals aren't focused on scope, but mention an out-of-scope scenario at some point. Often the snack topics are sensitive or rare (ish), and go into extra detail that most TPs won't need.
|
||||
|
||||
|
||||
|
||||
* Appear on the screen in body copy, for more common scenarios—Seen in Credits. These include a mention that some things are out-of-scope on the screen, usually with a snack link for more info. They're displayed as body copy, and are flagging scenarios that could save you money but won't get you in trouble if you get them wrong.
|
||||
* Appear on the screen in body copy, for more common scenarios—Seen in Credits. These include a mention that some things are out-of-scope on the screen, usually with a snack link for more info. They're displayed as body copy, and are flagging scenarios that could save you money but won't get you in trouble if you get them wrong.
|
||||
|
||||
|
||||
|
||||
|
|
@ -1054,7 +1051,7 @@ Tax return alert
|
|||
|
||||
A tax return alert is our mechanism for reporting in an assertive way on a problem or situation that calls for timely attention or intervention by the user and pertains to their return's content. The issue's level of consequence can range from moderate to high, but the information presented in an alert is generally reporting on a consequence impactful enough to (1) halt, (2) alter, or (3) endanger the user's ability to reach their end goal: successful filing.
|
||||
|
||||
Because of the level of consequence, these messages by definition must be assertive and therefore require a chain of cues (signposts) from UI-to-UI that highlight the issue and lead the user directly to the location in DF where they can review or resolve the condition that prompted the alert.
|
||||
Because of the level of consequence, these messages by definition must be assertive and therefore require a chain of cues (signposts) from UI-to-UI that highlight the issue and lead the user directly to the location in DF where they can review or resolve the condition that prompted the alert.
|
||||
|
||||
This definition differentiates the tax return alert from all other info box elements DF may use to explain, nudge, or provide other important information to the user even if the element uses warning or error styling, or status indicators that chain from UI-to-UI (like dependent/qp outcome flags). While those elements may be presented in reds and yellows, they don't meet the definition of tax return alerts.
|
||||
|
||||
|
|
@ -1070,7 +1067,7 @@ Errors are a forcing function: their behavior compels the user to resolve the co
|
|||
|
||||
#### **Special error type: Incompletes**
|
||||
|
||||
As DF works today, we force users to fill out all required fields on a page before saving it. Therefore, we don't expect there to be pages that have a mix of complete and incomplete fields.
|
||||
As DF works today, we force users to fill out all required fields on a page before saving it. Therefore, we don't expect there to be pages that have a mix of complete and incomplete fields.
|
||||
|
||||
Incomplete questions and collection items should be understood to be errors because they serve a forcing function: the user will be stopped from submitting their return while there are any missing pieces of required information. As errors, they are resolvable entirely in DF: it's a question of completion, which DF can validate.
|
||||
|
||||
|
|
@ -1100,13 +1097,13 @@ Because such warning alerts might not be resolvable in DF, they might not be som
|
|||
|
||||
Warnings don't force the user to resolve them, but they may give the user the opportunity to resolve them by changing answers or manually dismissing the alert. If the warning is at the page level, the user can save and continue or just leave the page by navigating away and they can still continue. If it's on the return level, they can still e-file or proceed on the paper path.
|
||||
|
||||
When warnings are used to report on a problem with the correctness of a tax return, it's in the situation where DF can't know if action the user takes in DF actually resolved the problem. This can only be known by submitting the return back to MeF. Or it may be entirely unresolvable in software and require real world action.
|
||||
When warnings are used to report on a problem with the correctness of a tax return, it's in the situation where DF can't know if action the user takes in DF actually resolved the problem. This can only be known by submitting the return back to MeF. Or it may be entirely unresolvable in software and require real world action.
|
||||
|
||||
Like error alerts, warning alerts are shown in response to a problem or a condition that the user needs to be aware of and warning alerts cover different levels of consequence: an unresolved warning can have no effect on the user's ability to complete their task or it can result in MeF rejection.
|
||||
|
||||
#### **System alert**
|
||||
|
||||
System alerts are critical messages DF displays to report on the state of the system or its success or failure executing a task.
|
||||
System alerts are critical messages DF displays to report on the state of the system or its success or failure executing a task.
|
||||
|
||||
### **Interaction and behavior:**
|
||||
|
||||
|
|
@ -1136,7 +1133,7 @@ Flattest presentation of alerts: Issue types should be presented in the flattest
|
|||
|
||||
4. Tax return alert error(s). These are any error that are neither MeF errors or field validation errors (e.g. your date of withdrawal has now passed, or forced-change error message for invalid filing status).
|
||||
|
||||
5. Summary of field validation errors (problem with format, required field blank, etc.): combine multiples in one alert block.
|
||||
5. Summary of field validation errors (problem with format, required field blank, etc.): combine multiples in one alert block.
|
||||
|
||||
6. MeF rejection return alert warning(s): don't combine, stack.
|
||||
|
||||
|
|
@ -1146,7 +1143,7 @@ Note: we don't show "resume" prompts on the page level, just dump you on the pag
|
|||
|
||||
#### **Reasoning**
|
||||
|
||||
System errors above all else: System errors are not caused by the user but it's critical the user have immediate awareness of problems DF is experiencing. It's the highest-priority type of error.
|
||||
System errors above all else: System errors are not caused by the user but it's critical the user have immediate awareness of problems DF is experiencing. It's the highest-priority type of error.
|
||||
|
||||
Don't hide other errors or messages if there's a system error: System errors should be shown above all else because they can prevent the user from taking any other action, including resolving other errors that might be reported on the page. Note that most of the time if there is a system error, it will be a whole-page error and the rest might not render at all. For any cases where such an error shows on a page with other content, it gets a top slot in the structure. We'd want to avoid flashing the other errors on and off in response to anything other than true resolution, so if there is a system error and other alerts, just show them all together stacked up.
|
||||
|
||||
|
|
@ -1160,15 +1157,15 @@ Flattest presentation of alerts: Issue types should be presented in the flattest
|
|||
|
||||
<img width="299" alt="Assertion_section_alert" src="https://github.com/user-attachments/assets/1ef98545-35f0-4b4f-9322-385c97ded294" />
|
||||
|
||||
When there is a Filing Status error (this is caused by changes outside the filing status section), the page the user sees is not the section's assertion data view anymore, it's a forced correction screen.
|
||||
When there is a Filing Status error (this is caused by changes outside the filing status section), the page the user sees is not the section's assertion data view anymore, it's a forced correction screen.
|
||||
|
||||
Assertion pages like the Amount page especially need a spot for messages because there can be warnings that direct the user to go finish items in other sections (like incomplete income items).
|
||||
|
||||
The Credits section has a conditional variation that uses an assertion as its data view instead of its usual data view. Its assertion variant may not generate errors of its own but still needs slots to display warnings.
|
||||
|
||||
#### **Assertion sections**
|
||||
#### **Assertion sections**
|
||||
|
||||
Assertion sections don't generally have input pages that will generate field validation errors, but they can generate errors or warnings of their own (like "you need to update your filing status" or someday they may give warnings like "I've changed since you last looked, review me.")
|
||||
Assertion sections don't generally have input pages that will generate field validation errors, but they can generate errors or warnings of their own (like "you need to update your filing status" or someday they may give warnings like "I've changed since you last looked, review me.")
|
||||
|
||||
Like any DF page, they need to be able to display errors and warnings.
|
||||
|
||||
|
|
@ -1178,7 +1175,7 @@ I don't yet foresee any of the current assertion sections getting MeF errors or
|
|||
|
||||
#### **What kinds of alerts will they have?**
|
||||
|
||||
The errors and warnings they do display will tend to be explanations about something the TP changed elsewhere in the return that caused or necessitated a change here.
|
||||
The errors and warnings they do display will tend to be explanations about something the TP changed elsewhere in the return that caused or necessitated a change here.
|
||||
|
||||
Warnings might include awareness messages like "you have items in progress that may affect this amount. Go finish them."
|
||||
|
||||
|
|
@ -1250,11 +1247,11 @@ The return status banner is reserved for return-level flags that should be prese
|
|||
|
||||
* Your filing method is limited to the paper path
|
||||
|
||||
* Knockout state
|
||||
* Knockout state
|
||||
|
||||
* Submitted (pending) / Accepted
|
||||
|
||||
* Rejected
|
||||
* Rejected
|
||||
|
||||
The aggregate summary banner follows these rules:
|
||||
|
||||
|
|
@ -1320,7 +1317,7 @@ Return status banner
|
|||
|
||||
<img width="773" alt="return_status_banner" src="https://github.com/user-attachments/assets/5b778988-e101-4675-970b-5e9dc7be1729" />
|
||||
|
||||
This spot is reserved for return-level status flags that should be presented on their own like
|
||||
This spot is reserved for return-level status flags that should be presented on their own like
|
||||
|
||||
* In progress
|
||||
|
||||
|
|
@ -1328,9 +1325,9 @@ This spot is reserved for return-level status flags that should be presented on
|
|||
|
||||
* Knockout state
|
||||
|
||||
* Submitted (pending) / Accepted
|
||||
* Submitted (pending) / Accepted
|
||||
|
||||
* Rejected
|
||||
* Rejected
|
||||
|
||||
* Post-submission errors: a catch all for tax returns that will never reach "accepted" or "rejected" status without DF product intervention. Why? Because MeF doesn't think the federal tax return exists, for example. There may be other errors we encounter after launch.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# Design and a11y review process
|
||||
|
||||
The below steps are specifically the design and accessibility testing part of the overall acceptance flow process. The code submitter should have done their due dilligence for any user interface changes so that a design/a11y reviewer can focus on finer details. Although there are several steps, if we do this regularly it will be a light lift and will avoid any design/a11y debt.
|
||||
The below steps are specifically the design and accessibility testing part of the overall acceptance flow process. The code submitter should have done their due diligence for any user interface changes so that a design/a11y reviewer can focus on finer details. Although there are several steps, if we do this regularly it will be a light lift and will avoid any design/a11y debt.
|
||||
|
||||
## Verify that any changes match the design intention
|
||||
|
||||
|
|
|
|||
|
|
@ -1,36 +1,37 @@
|
|||
Created At: May 5, 2024
|
||||
Updated At: May 14, 2024
|
||||
Created At: May 5, 2024
|
||||
Updated At: May 14, 2024
|
||||
|
||||
RFC: Evolving How We Align on Technical Decisions
|
||||
|
||||
|
||||
# Problem Statement
|
||||
|
||||
Direct File has matured as an application over the past year (read: we went to production) and grew its headcount to a 70+ member product team. However, we have not invested a lot of resources into adapting our processes around technical decision making to our burgeoning scale. This has manifested itself in last-mile delivery delays for various initiatives, primarily due to the fact that the right stakeholders were not in the room at the appropriate moments or they did not know that a decision was being made until after the fact.
|
||||
|
||||
Similarly, as Direct File grows in product scope, our relationship with the larger IRS IT organization will both change and become increasingly important. Integrating our ways of working during the pilot to the processes of the IRS enterprise more broadly will require a different approach than what served us during the pilot.
|
||||
Similarly, as Direct File grows in product scope, our relationship with the larger IRS IT organization will both change and become increasingly important. Integrating our ways of working during the pilot to the processes of the IRS enterprise more broadly will require a different approach than what served us during the pilot.
|
||||
|
||||
# BLUF: Proposed Process Changes
|
||||
|
||||
1. Distinguish RFCs from ADRs and clarify when to leverage each one
|
||||
2. Establish a dedicated meeting time, with defined decision-makers, for reviewing RFCs that did not achieve alignment during async review
|
||||
3. Include IRS IT SMEs within the RFC process and identify the criteria under which they should be engaged for certain changes
|
||||
|
||||
|
||||
# Definitions
|
||||
|
||||
Request For Comments (RFC): In the engineering context, a formal document that recommends a technical specification for a set of product requirements. This can include anything from a change solely at the application level to a system(s)-wide, architecture that engages with multiple external services. Typically contains a set of working definitions, articulation of key product requirements, proposed implementation and analysis of alternatives. If the RFC is approved, it becomes the touchpoint for technical implementation and should be revised according to if new requirements appear. Some RFC are designated indefinitely with Experimental or Draft status.
|
||||
|
||||
Architecture Decision Record (ADR): A “lightweight” document that captures the rationale of a Architectural Decision (AD), i.e. a justified design choice that addresses a functional or non-functional requirement that is architecturally significant. ADRs captures a single AD and its rationale; the collection of ADRs created and maintained in a project constitute its decision log. ADRs typically contains a title, status, context, decision, and consequences.
|
||||
|
||||
|
||||
# Proposal
|
||||
|
||||
## Goal
|
||||
|
||||
The goal of this proposal is to find the right balance between:
|
||||
|
||||
1) Functioning in an product-centric, agile manner;
|
||||
2) Not constraining ourselves with unnecessary overhead; and
|
||||
2) Not constraining ourselves with unnecessary overhead; and
|
||||
3) Clearly understanding the when, who and how of engaging with our IRS IT counterparts at the appropriate times.
|
||||
|
||||
The remainder of this proposal deals with some ways we can balance these needs and achieve these goals.
|
||||
|
||||
The remainder of this proposal deals with some ways we can balance these needs and achieve these goals.
|
||||
|
||||
## Deepen our understand and engagement with the IRS IT organization and get our IRS IT SMEs involved as early as possible
|
||||
|
||||
|
|
@ -39,33 +40,36 @@ We should engage with, at a minimum, our embedded Cyber SME and Technical Adviso
|
|||
IRS IT SMEs should be involved when a system-wide change is being proposed, in particular one that might involve an update to any part of our ATO and especially control implementation statements in our System Security Plan (SSP). These changes typically require updating the `application.boundary` or `application.context` compliance documentation at some stages.
|
||||
|
||||
### When should I loop in IRS IT SMEs?
|
||||
Examples of "system-wide changes" includes, but are not limited to:
|
||||
- Provisioning new cloud infrastructure, both compute and storage
|
||||
- Requesting changes to how our network boundaries are configured
|
||||
- Adding new API endpoints or modifying where a URI can be located (i.e. changing the structure of the endpoint)
|
||||
- New vulnerability scan findings that cannot be remediated timely
|
||||
- Changing any part of our authorization or authentication flow
|
||||
- Storing or accessing SBU/PII/FTI in an environment that isn't the application database or cache (in particular SaaS tools)
|
||||
- Deviation from IRS IRMs
|
||||
- Data or container security
|
||||
- Integrating with other parts of the IRS (enterprise services, on-prem, cloud, etc.)
|
||||
- Establishing connections external to the IRS
|
||||
- Requesting new tools (whether or not they are ESP or COE approved)
|
||||
- Major version upgrades of software framework components
|
||||
- Standing up new deployed services
|
||||
|
||||
Examples of "system-wide changes" includes, but are not limited to:
|
||||
|
||||
- Provisioning new cloud infrastructure, both compute and storage
|
||||
- Requesting changes to how our network boundaries are configured
|
||||
- Adding new API endpoints or modifying where a URI can be located (i.e. changing the structure of the endpoint)
|
||||
- New vulnerability scan findings that cannot be remediated timely
|
||||
- Changing any part of our authorization or authentication flow
|
||||
- Storing or accessing SBU/PII/FTI in an environment that isn't the application database or cache (in particular SaaS tools)
|
||||
- Deviation from IRS IRMs
|
||||
- Data or container security
|
||||
- Integrating with other parts of the IRS (enterprise services, on-prem, cloud, etc.)
|
||||
- Establishing connections external to the IRS
|
||||
- Requesting new tools (whether or not they are ESP or COE approved)
|
||||
- Major version upgrades of software framework components
|
||||
- Standing up new deployed services
|
||||
|
||||
## Leverage RFCs as the primary mechanism to propose technical specifications
|
||||
|
||||
We currently conflate the concept of an ADR with an RFC. ADRs are static artifacts that are post-decisional; an engineer should be able to read the entire decision log of ADRs and roughly understand why the system is configured as it is. RFCs, on the other hand, are live documents meant for discussion and iteration. They are better suited for soliciting input and collecting feedback on a proposed approach, which is the right first step for proposing a technical specification. The outcome of an RFC might be an ADR, if the scale of proposed change merits it.
|
||||
|
||||
In practice, this means that once engineers are given a sufficiently large or complex set of requirements, they articulate their proposed approach in an RFC, rather than a combination of Gitlab tickets, Slack threads, and markdown files committed to the codebase with the word "ADR" in the title. This forces the engineer to spend more time substantiating their reasoning for a certain implementation and weighing various alternatives, as well as investigating the various upstream and downstream dependencies of the proposal. It also requires the engineer to consolidate their thoughts into a single SOT document, reducing the cognitive overhead of all participants of tracking the outcome across multiple surfaces (Github, Gitlab, Slack, Teams, etc.).
|
||||
|
||||
Writing an RFC **does not** negate the need to prototype various solutions; rather, prototyping should be considered part of the RFC process as a way to demonstrate the feasability of a given approach and that alternatives were considered.
|
||||
Writing an RFC **does not** negate the need to prototype various solutions; rather, prototyping should be considered part of the RFC process as a way to demonstrate the feasibility of a given approach and that alternatives were considered.
|
||||
|
||||
Importantly, designing larger features and broader architecture design has historically been limited to a small number of developers relative to the size of the engineering organization, limiting the ability for other engineers to contribute and grow as system designers. This is mostly due to reasons of velocity and speed necessary to get the pilot out the door. RFCs provide a mechanism through which to enable other engineers to own their features end-to-end, instead of relying on another engineer to propose the implementation which they then action.
|
||||
Importantly, designing larger features and broader architecture design has historically been limited to a small number of developers relative to the size of the engineering organization, limiting the ability for other engineers to contribute and grow as system designers. This is mostly due to reasons of velocity and speed necessary to get the pilot out the door. RFCs provide a mechanism through which to enable other engineers to own their features end-to-end, instead of relying on another engineer to propose the implementation which they then action.
|
||||
|
||||
## Add a synchronous, cross-org forum for discussing RFCs that are not resolved asynchronously
|
||||
In addition to moving to a world where RFCs are the formal document that facilitate discussion, we should also move away from a model where major engineering decisions are both reviewed and approved by a single functional team in a predominately asynchronous, i.e. in Github PRs. Instead, we should move towards a model where a broader audience can weigh in on proposed changes and discuss outstanding questions in a synchronous manner.
|
||||
|
||||
In addition to moving to a world where RFCs are the formal document that facilitate discussion, we should also move away from a model where major engineering decisions are both reviewed and approved by a single functional team in a predominately asynchronous, i.e. in Github PRs. Instead, we should move towards a model where a broader audience can weigh in on proposed changes and discuss outstanding questions in a synchronous manner.
|
||||
|
||||
Making RFC review into a blocking mechanism is not the goal. Synchronous time should be leveraged **only** when there are outstanding questions on a proposal that require live, cross-team discussion. While async review and approval is always the first and best option, practically speaking at a certain level of system change, live discussion is inevitable if not necessary. We should embrace that reality, not fight it and rely on back-channels and 100-comment Slack thread to facilitate alignment on major changes.
|
||||
|
||||
|
|
@ -73,42 +77,43 @@ Tactically, this would involve adding a standing RFC-review meeting that is 1) t
|
|||
|
||||
One key benefit here is that a cross-organization, discussion-based approach to RFCs reduces knowledge silos across the product organization and allows engineers to better 1) understand what is happening across different teams; and thus 2) flag cross-cutting concerns that might not have been addressed during the primary review phase (e.g. changes to authn/authz affects many different teams, but not every team might be involved as the primary reviewers).
|
||||
|
||||
|
||||
### Why a standing meeting instead of as needed/ad-hoc?
|
||||
|
||||
While the flexibility of ad-hoc better mirrors our historical and current practices around engineering meetings, there are a few reasons why a standing meeting with the sole purpose of reviewing RFCs is beneficial, at least in the first instance:
|
||||
|
||||
1. The right people are always in the room: the blended team model create a world where no single individual has access to everyone's calendar. By maintaining a standing meeting, everyone must put re-occuring blocks on their respective calendars, greatly increasing the chance that if they are a stakeholder, they will be able to attend.
|
||||
1. In this vein, we want to ensure that our key IRS IT counterparts - those with a known stake in facilitating the delivery of the technical output - have their concerns are addressed before proceeding to implementation. This reduces our overall delivery lead time by removing "unknown unknowns" and proactively identifying (and accounting for) process-based roadblocks much earlier in the delivery process.
|
||||
1. The right people are always in the room: the blended team model create a world where no single individual has access to everyone's calendar. By maintaining a standing meeting, everyone must put re-occurring blocks on their respective calendars, greatly increasing the chance that if they are a stakeholder, they will be able to attend.
|
||||
1. In this vein, we want to ensure that our key IRS IT counterparts - those with a known stake in facilitating the delivery of the technical output - have their concerns are addressed before proceeding to implementation. This reduces our overall delivery lead time by removing "unknown unknowns" and proactively identifying (and accounting for) process-based roadblocks much earlier in the delivery process.
|
||||
2. Resolving opposing views: major engineering changes often have several viable paths, and it is rare to have all outstanding questions answered asynchronously. A standing meeting releases both the author and reviewer from "finding a time to hash it out live" in favor of using a dedicated mechanism like RFC review (with an agenda and time limit on topics) to facilitate to discussion. This reduces unnecessary friction within and across teams, and enables other members of the organization to manage the discussion.
|
||||
3. Context sharing and maintaining visibility for other teams and leadership: As Direct File grows, it is unrealistic that the people who might have reviewed PRs during the pilot will have the time to do so in Year 2, 3, etc. This doesn't mean, however, that they want to be divorced from the technical discussions that are happening. A standing meeting provides a dedicated space for those members/leadership to keep a finger on the pulse of what is happening without reviewing a dozen RFCs a week.
|
||||
4. It is easier to start with a standing meeting and move to ad-hoc later than vice versa. Especially as we build the organizational muscles around a process like RFC review, it is helpful to have the meeting in place instead of requiring individuals to advocate for ad-hoc meetings out of the gate. During filing season, for instance, I expect us to leverage ad-hoc meetings significantly more. Conversely, during May-September when a lot of planning and technical designs are choosen, we would benefit from a standing meeting to make sure we aren't crossing-wires and are moving in lockstep.
|
||||
5.
|
||||
4. It is easier to start with a standing meeting and move to ad-hoc later than vice versa. Especially as we build the organizational muscles around a process like RFC review, it is helpful to have the meeting in place instead of requiring individuals to advocate for ad-hoc meetings out of the gate. During filing season, for instance, I expect us to leverage ad-hoc meetings significantly more. Conversely, during May-September when a lot of planning and technical designs are chosen, we would benefit from a standing meeting to make sure we aren't crossing-wires and are moving in lockstep.
|
||||
5.
|
||||
|
||||
# Appendix I: Step-by-Step examples of how this all works in practice
|
||||
If implemented, the expected development lifecycle would look roughly as follows:
|
||||
|
||||
If implemented, the expected development lifecycle would look roughly as follows:
|
||||
|
||||
**note: Each team/group/pod maintains autonomy in terms of how they want to define and implement the various steps, as long as 1) async and sync RFC review is incorporated into their development; and 2) IRS IT SMEs are engaged at the appropriate moments. The below will not map perfectly onto any given team's cadence, and instead aims to approximate the most-process heavy approach from which team's can choose what they would like to incorporate.**
|
||||
|
||||
1. Product requirements for a feature set are specified in a ticket (by someone)
|
||||
2. The Directly Responsible Engineer (DRE) provides an intial, rough estimate of the scope and sizing of the work, as well as the documentation required to drive alignment on an orginizationally acceptable approach:
|
||||
2. The Directly Responsible Engineer (DRE) provides an initial, rough estimate of the scope and sizing of the work, as well as the documentation required to drive alignment on an organizationally acceptable approach:
|
||||
1. If a system-wide change (see below for criteria) is involved, an RFC and ADR will be required before moving to any implementation. **IRS IT SMEs should be looped in early as key stakeholders and reviewers.**
|
||||
2. If the feature set is not a system-wide change, the DRE has discretion about if an RFC would be a helpful tool to facilitate design and/or gain consensus within a team or across teams. Some feature sets are complex enough to benefit from an RFC; others are not. Once the RFC is drafted, reviewed and approved, the DRE can begin implementation.
|
||||
3. If an RFC is not needed, the DRE can immediately begin implementation and put up a PR with a description of the work and link back to the ticket.
|
||||
3. If an RFC is needed, the DRE drafts a written proposal as a means to solicits feedback on the proposed technical approach. The document should live in the `docs/rfc` directory and be committed to the codebase in a PR in a text format like Markdown with associated artifacts (diagrams, etc.) included as needed.
|
||||
1. All initial discussion can happen asynchronously and ad-hoc.
|
||||
2. If a system-wide change is being proposed, DevOps and our IRS IT colleagues (in partiular Cyber SME and Technical Advisor) should be looped in at this stage as reviewers.
|
||||
3. If an RFC is needed, the DRE drafts a written proposal as a means to solicits feedback on the proposed technical approach. The document should live in the `docs/rfc` directory and be committed to the codebase in a PR in a text format like Markdown with associated artifacts (diagrams, etc.) included as needed.
|
||||
1. All initial discussion can happen asynchronously and ad-hoc.
|
||||
2. If a system-wide change is being proposed, DevOps and our IRS IT colleagues (in particular Cyber SME and Technical Advisor) should be looped in at this stage as reviewers.
|
||||
3. If a system-wide change is not being proposed, the DRE and reviewers should use their discretion as to if IRS IT should be engaged or not during the RFC stage. **If they are not engaged, the assumption is that they will not need to be engaged during or after implementation.**
|
||||
4. If all questions (including those from IRS IT colleagues) are sufficiently addressed in the written RFC, the RFC can be approved and the DRE can move to implementation.
|
||||
5. If there are outstanding questions in the RFC that cannot be resolved asynchronously, the RFC is slotted for discussion during the standing "RFC Review" meeting and circulated for discussion to all RFC Review participants.
|
||||
1. During the meeting, the DRE presents a summary of the proposed changes and the group discusses the main outstanding questions and aligns on a path forward.
|
||||
2. The DRE updates the RFC as needed coming out of this meeting.
|
||||
5. If there are outstanding questions in the RFC that cannot be resolved asynchronously, the RFC is slotted for discussion during the standing "RFC Review" meeting and circulated for discussion to all RFC Review participants.
|
||||
1. During the meeting, the DRE presents a summary of the proposed changes and the group discusses the main outstanding questions and aligns on a path forward.
|
||||
2. The DRE updates the RFC as needed coming out of this meeting.
|
||||
3. n.b. **this is the only synchronous portion of this process, everything else is asynchronous**
|
||||
6. In the event that an ADR is needed, after the RFC stage is complete an ADR is drafted and committed to the codebase in the `docs/adr` repository. This should all occur asynchronously and should be merged in short order with minimal review cycles.
|
||||
6. In the event that an ADR is needed, after the RFC stage is complete an ADR is drafted and committed to the codebase in the `docs/adr` repository. This should all occur asynchronously and should be merged in short order with minimal review cycles.
|
||||
1. No alignment is needed on the ADR as it simply codifies the outcome of the RFC and RFC review.
|
||||
7. Once the RFC and/or ADR stages are complete, the DRE can begin implementation. At the same time, they also coordinate with IRS IT and DevOps to understand if they need any additional documentation aside from the RFC and ADR is necessary to initiate or facilitate IRS IT or IEP processes.
|
||||
|
||||
|
||||
# Appendix II: Deciding between RFC, ADR and normal PRs
|
||||
|
||||
This section provides a basic decision tree for deciding between the following processes (in order of number of parties that need to coordinate to make a change, from least to most):
|
||||
|
||||
- Ticket with a PR
|
||||
|
|
@ -132,7 +137,7 @@ In general, default to the process requiring the least coordination available if
|
|||
2. Major additions or modifications to the UX flow
|
||||
3. Implementing new tax logic within the flow/fact graph
|
||||
4. Implementing or modifying retry logic for certain backend processes (e.g. sending email)
|
||||
5. Requesting infrastructure configuration changes for previously-provisioned resources, such as changing the redrive policy on SQS for certain queues
|
||||
5. Requesting infrastructure configuration changes for previously-provisioned resources, such as changing the redrive policy on SQS for certain queues
|
||||
5. Does the feature set have pre-existing, well defined product and technical requirements? -> PR/ticket is sufficient, no need for RFC or ADR
|
||||
1. Modifying pre-existing tax logic within the flow/fact graph
|
||||
2. Adding new repositories,interfaces, classes, services, etc. that clean up parts of the codebase
|
||||
|
|
@ -140,6 +145,3 @@ In general, default to the process requiring the least coordination available if
|
|||
4. Spring-ifying the backend services
|
||||
5. Updating dependencies
|
||||
6. Remediating security findings
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue