Label each field with which intent template that it is used in

[DanielRyanSmith]

Fixes #5495

This change adds new icons next to fields that clarify which fields are used in which intent templates.

Note that I had to cross-reference our intent_to_implement.html file to ensure I was capturing which fields are available in which template, and I believe I'm close to correct in documenting the field usage in intents through form-field-specs. If certain fields are strangely marked as unused or not in certain templates, this is likely a flaw our current intent template.

Example of changes:
Screen recording 2025-10-09 11.36.23 AM.webm

[jcscottiii]

This is a great PR, and the feature is a valuable addition.

One suggestion to improve the TypeScript implementation would be to refactor the FEATURE_TYPE_*_ID constants into a proper enum.

For example, in client-src/elements/form-field-enums.ts, you could define:

export enum FeatureType {
  Incubate = 0,
  Existing = 1,
  CodeChange = 2,
  Deprecation = 3,
  Enterprise = 4,
}

This would provide several benefits:

1. Enhanced Type Safety: It creates a distinct FeatureType type, preventing the use of arbitrary numbers where a feature type is expected.
2. Improved Readability: Using FeatureType.Incubate is more descriptive and less prone to error than using a magic number like 0.
3. Better Maintainability: It groups all related feature type constants into a single, cohesive definition.

This change would also allow for much stronger typing of related data structures. For instance, the FieldIntentUsage interface in client-src/elements/form-field-specs.ts could be simplified from its current form to:

export type FieldIntentUsage = Partial<Record<FeatureType, Set<IntentType>>>;

This is a more robust and idiomatic TypeScript approach that would allow the compiler to catch any missing feature types in structures like ALL_INTENT_USAGE_BY_FEATURE_TYPE.

---

This review was provided by Gemini CLI powered by GitHub MCP Server

[jcscottiii]

I was a little AI happy 😅 with the review. But let me take a look now lol

[jcscottiii]

LGTM. Let me know your thoughts on the suggestions from AI and me.

[jcscottiii]

Similar to the AI suggestion, you could do something like this to help with typing:

 interface IntentTypeDetail {
   abbreviation: string;
   className: string;
   title: string;
 }
 
 const INTENT_TYPE_DETAILS: Record<IntentType, IntentTypeDetail> = { ... };

[DanielRyanSmith]

All of the above are great suggestions, and I've implemented them! 🙂

[jrobbins]

I have concerns about two aspects of this change:

• I don't want to encourage users to take the path of least resistance to only fill in fields that are needed for a particular intent. All the fields are supposed to be useful to some reviewer or for release notes, so really they should all be filled in, if they are applicable to the feature at hand. Also, even the API Owners are supposed to be reviewing the totality of the feature entry, not just what is included in the intent, so feature owners really shouldn't be skipping a field that lacks a label.
• A single-letter label is not going to be obvious to users. Hover text helps, but it would be better to use well-known acronyms. E.g., "I2P", "I2E", "I2S".

What if we just put a brief notation in the field-level help text? E.g., for "Flag Name", it could be:

Name of the flag on about://flags that allows a web developer to
enable this feature in their own browser to try it out. E.g., "storage-buckets". These are defined
in about_flags.cc. Included in intent-to-ship email.

[DanielRyanSmith]

I don't want to encourage users to take the path of least resistance to only fill in fields that are needed for a particular intent. All the fields are supposed to be useful to some reviewer or for release notes, so really they should all be filled in, if they are applicable to the feature at hand. Also, even the API Owners are supposed to be reviewing the totality of the feature entry, not just what is included in the intent, so feature owners really shouldn't be skipping a field that lacks a label.

I do understand the concern here, but this has been a repeated pain point for multiple users. The information can be derived from looking at the intent templates, but that's the pain point that surfaces - users don't realize which fields get surfaced in the intent and which do not.

For example, a user might add an important caveat in the "Comments" field rather than the summary field, but then not realize that now the intent email will not surface this caveat because the "Comments" field is not in the intent, so the intent feels like it is missing information.

I think I'm of the opinion that, since all of this information is public, if a field is truly important for the launch process, it should just be surfaced in the intent as well. Obfuscating what fields are part of which intent in order to encourage completion is probably more of a symptom of intents not containing the information they should.

A single-letter label is not going to be obvious to users. Hover text helps, but it would be better to use well-known acronyms. E.g., "I2P", "I2E", "I2S".

I definitely agree with this, and since this PR is using "PSA", three-letter icons are in the mix already. I can add this change 🙂

What if we just put a brief notation in the field-level help text? E.g., for "Flag Name", it could be:

Name of the flag on about://flags that allows a web developer to
enable this feature in their own browser to try it out. E.g., "storage-buckets". These are defined
in about_flags.cc. Included in intent-to-ship email.

This gets murky with all of the conditional logic that we use in our intent generation. We would then need description modifiers for each feature type as well as intent type, for instance. It seems more difficult to maintain accurate descriptions and make intent changes in this case.

[jrobbins]

The problem with labeling the fields that is used in intents is that it implies that the other fields that are not labeled with anything are not useful for anything. So, let's label everything. The intent_usage spec field would become just usage and in addition to I2P, I2S, I2E, and I2S values, it could also have:

• XFN for cross-functional reviews (without displaying the team name because that is too close to how we label gate chips)
• RN for release notes, beta blog, web.dev posts, and other devrel-type communications

That would leave just a few fields unlabeled, but their purpose should be clear from the name, or in some cases they truly are rarely used, e.g., comments.

[DanielRyanSmith]

The problem with labeling the fields that is used in intents is that it implies that the other fields that are not labeled with anything are not useful for anything. So, let's label everything. The intent_usage spec field would become just usage and in addition to I2P, I2S, I2E, and I2S values, it could also have:

• XFN for cross-functional reviews (without displaying the team name because that is too close to how we label gate chips)
• RN for release notes, beta blog, web.dev posts, and other devrel-type communications

That would leave just a few fields unlabeled, but their purpose should be clear from the name, or in some cases they truly are rarely used, e.g., comments.

I like this approach 🙂

Is there a place I can discern this mapping within our codebase?

[jrobbins]

I like this approach 🙂

Is there a place I can discern this mapping within our codebase?

No, this would be making it explicit for the first time. If you specify screenshot_links as RN for all feature types, and enterprise_policies as XFN for all feature types, then I will follow up with a PR to add other types of usage to more other fields

[jrobbins]

The change looks good. But some of the playwright snapshots look like there was a change to the main menu, maybe because of spacing. Was that expected?

[DanielRyanSmith]

But some of the playwright snapshots look like there was a change to the main menu, maybe because of spacing. Was that expected?

For the main menu, I believe that the actual change is some form spacing, and the only thing that's not changing in spacing is the main menu - but this makes it look like the main menu is changing because the playwright test screenshot is centered around a specific location in the form. 😅