Improving the feature type descriptions in Chrome Status

[Jeffrey Yasskin]

We keep having feature owners pick the wrong feature type in Chrome Status and then getting stuck when they need to do something the feature type doesn't allow. In various discussions, it has sounded like the fundamental distinction between the types is "add", "remove", and "no change", with a subset of "add" being things that have already mostly gotten consensus. So I put together https://github.com/GoogleChrome/chromium-dashboard/pull/4106 to try to reflect that in the tool.

My current proposed wording is as follows, but I hope you all will help refine it:

Thanks,

Jeffrey

[Chris Harrelson]

This leaves out the "change to existing feature" category. Change "new feature" to "new feature or developer-visible change to existing feature"?

--
You received this message because you are subscribed to the Google Groups "blink-api-owners-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to blink-api-owners-d...@chromium.org.
To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-api-owners-discuss/CANh-dXmVFfb3FJ8otSsdRc%2BZ3fPfawWM5v4YVWqSmqivYxFG9A%40mail.gmail.com.

[Jeffrey Yasskin]

In the interest of keeping the headings short, maybe "New or changed feature"? Then I've noticed that changes often involve a pair of entries, so I'll add "Note that backward-incompatible changes sometimes need to be implemented as a pair of adding the new behavior and a separate entry to remove the old behavior." to the description.

[Jeffrey Yasskin]

Your difficulties with this got me over the hump of trying to fix the description, but I didn't realize you'd filed an issue about it. Thoughts:

1. Moving this field to the top is straightforward and separable from the rewording. I'll send another PR to do that, but probably Monday.

2. I'm not sure how much detail to go into. The definitions of the differences are in https://github.com/GoogleChrome/chromium-dashboard/blob/7f37bd7c/client-src/elements/form-definition.ts#L755 and https://github.com/GoogleChrome/chromium-dashboard/blob/7f37bd7c/internals/processes.py#L185. I'm hopeful that rephrasing the PSA option as "developers should see no change" will prevent people from picking that option in cases that need LGTMs, so I don't want to spend space saying that it won't let you collect LGTMs. (And it actually does let you collect LGTMs in the tool, which the process says it shouldn't.) I did mention the missing fields that have come up in the "Existing feature" vs "New feature" distinction. Do folks have particular changes that'd help?

3. I think my PR accomplishes the renaming you asked for.

On Thu, Jul 11, 2024 at 4:47 PM Mason Freed <mason...@google.com> wrote:

Coincidentally (or maybe not?) I just opened 

https://github.com/GoogleChrome/chromium-dashboard/issues/4102 this morning for this very reason. I like your new wording, but there are a few more suggestions from my bug that you might want to consider. In particular, including (in detail) the consequences of each selection, such as LGTM approval or not. Generally, I think this selection should be very verbose and err on the side of too much info. Primarily because it’s irreversible.

I’d second Chris’ suggestion to include developer-visible changes to existing APIs.

Thanks,

Mason

[Mason Freed]

Coincidentally (or maybe not?) I just opened 

https://github.com/GoogleChrome/chromium-dashboard/issues/4102 this morning for this very reason. I like your new wording, but there are a few more suggestions from my bug that you might want to consider. In particular, including (in detail) the consequences of each selection, such as LGTM approval or not. Generally, I think this selection should be very verbose and err on the side of too much info. Primarily because it’s irreversible.

I’d second Chris’ suggestion to include developer-visible changes to existing APIs.

Thanks,

Mason

On Thu, Jul 11, 2024 at 4:11 PM Jeffrey Yasskin <jyas...@google.com> wrote:

[Chris Harrelson]

"New or changed feature" SGTM! Short headlines sounds good to me. Though verbose secondary explanation text also seems justified, for the "it's irreversible" reason Mason mentioned. I've seen this problem happen maybe 10 times so far.

[Mason Freed]

On Fri, Jul 12, 2024 at 9:24 AM Chris Harrelson <chri...@chromium.org> wrote:

"New or changed feature" SGTM! Short headlines sounds good to me. Though verbose secondary explanation text also seems justified, for the "it's irreversible" reason Mason mentioned. I've seen this problem happen maybe 10 times so far.

+1. Especially if this is the first page of the "new entry" flow, it can be long and wordy. The titles should be clear, since most people will start there and pick one without reading the details. But when they're confused about the options, they will then read the text looking for details. In particular, I'd really like to see the "consequences" of choosing each option. The descriptions I see in the PR still talk only about the "kind" of change being made, but not what happens if you pick that option. For example, I'm still very confused about the difference between "New or changed feature" and "Chromium finally implemented a feature". I'd likely pick the first one for almost everything, but what's different if I choose the second one? Many of my recent changes fall in between these two options, and I'm really unclear which is correct. Concretely, we renamed the `inset-area` property to `position-area`, because CSSWG resolved to do that. That's not a new feature, but it is a changed feature, so I'd be inclined to choose the first one. But the description for "Chromium finally implemented a feature" says "choose this if a standards body already has consensus", and that's precisely what happened to trigger this change, so now I'd be inclined to choose the second option.

Can we just combine the first and second entries into "New or changed developer-visible feature" and eliminate the "chromium finally implemented a feature" selection? 

 

On Thu, Jul 11, 2024 at 5:14 PM Jeffrey Yasskin <jyas...@google.com> wrote:

Your difficulties with this got me over the hump of trying to fix the description, but I didn't realize you'd filed an issue about it. Thoughts:

1. Moving this field to the top is straightforward and separable from the rewording. I'll send another PR to do that, but probably Monday.

Awesome, thanks! 

2. I'm not sure how much detail to go into. The definitions of the differences are in https://github.com/GoogleChrome/chromium-dashboard/blob/7f37bd7c/client-src/elements/form-definition.ts#L755 and https://github.com/GoogleChrome/chromium-dashboard/blob/7f37bd7c/internals/processes.py#L185. I'm hopeful that rephrasing the PSA option as "developers should see no change" will prevent people from picking that option in cases that need LGTMs, so I don't want to spend space saying that it won't let you collect LGTMs. (And it actually does let you collect LGTMs in the tool, which the process says it shouldn't.) I did mention the missing fields that have come up in the "Existing feature" vs "New feature" distinction. Do folks have particular changes that'd help?

More detail is better. The titles should be as descriptive as possible, so folks don't have to read the extra stuff. But in unclear cases, the extra stuff is critical. Like I literally still don't know which option to choose for my `inset-area` change.

 

3. I think my PR accomplishes the renaming you asked for.

Definitely getting better. I like the PSA option wording a lot better now.

[Yoav Weiss (@Shopify)]

Looks great!

One nit: maybe "Chromium catches up" instead of "Chromium finally implemented"? Also, why is this category important (compared to "new or changed feature")? Is the process somehow different from "new or changed"?

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-api-owners-discuss/CAM%3DNeDiFPvD9p8zLx_zSc4RA8gRDnE%2BCAt2x29zVj_19bZ2-3Q%40mail.gmail.com.

[Jeffrey Yasskin]

I can change that. This category is _not_ important, and Mike Taylor and I have plans to get rid of it, but doing that takes more work than fixing the descriptions. I realized that we could help a bunch of feature developers quickly by rewording the current imperfect set of options instead of waiting until the better set of options is ready. 

Jeffrey

[Yoav Weiss (@Shopify)]

On Mon, Jul 15, 2024 at 3:54 PM Jeffrey Yasskin <jyas...@google.com> wrote:

I can change that. This category is _not_ important, and Mike Taylor and I have plans to get rid of it, but doing that takes more work than fixing the descriptions. I realized that we could help a bunch of feature developers quickly by rewording the current imperfect set of options instead of waiting until the better set of options is ready. 

Changing the wording now and getting rid of it later SGTM!

[Mike Taylor]

Coming to this late, but +1. :)

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-api-owners-discuss/CAOmohSLv1mH2fTikXb1hV%2BeANe%3DXOMiL0_b7H2ePsCbtSmURAw%40mail.gmail.com.

[Jeffrey Yasskin]

I've sent https://github.com/GoogleChrome/chromium-dashboard/pull/4123 to move the Feature Type field to the top of the New Feature page. Please comment there if you think it's a bad idea.

I also merged https://github.com/GoogleChrome/chromium-dashboard/pull/4106 with the wording changes we'd discussed so far. I think it's plausible to describe the exact differences between "New or changed" and "catches up" in this text, but I don't have time to do that before I go on vacation, and I wanted to get some improvement landed.