Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

refactor the proposal stages table for better communication #38

Merged
merged 8 commits into from
Feb 6, 2024

Conversation

michaelficarra
Copy link
Member

@michaelficarra michaelficarra commented Dec 5, 2023

As we discussed in plenary, this is an incorporation of the presented "purpose", "status", and "external communication" terms into the stage table of the process document. Additionally, the table is simplified by reducing to 4 columns from 7 without losing any information. The "status" column is targeted at the community and other external consumers, and the entrance criteria and purpose columns are targeted at champions and other TC39 representatives. Help text for the "purpose" column clarifies that "These are the actions that will be undertaken by the committee and the proposal authors while the proposal is in this stage".

While it is mostly a rewording, there are some "normative" changes made that I think more accurately capture how we use our process in practice:

  • Moved "Proposal document describes all high-level APIs and syntax" and "Illustrative examples of usage" from stage 1 entrance criteria to stage 2 entrance criteria.
  • Replace references to "ECMAScript editors" and "ecma262" with "the relevant editor group" and "ecma262 or ecma402" so that the document applies correctly to Intl proposals
  • Removed test262 entrance criteria from stage 4 since it's now already required for stage 3.

Since it's been mostly rewritten, I'd recommend reviewing the rendering instead of the diff.

Here's a rendering of the table as of submitting this PR:

image

Ping @waldemarhorwat since he asked to be notified when I opened this PR.

Copy link
Member

@ljharb ljharb left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overall this looks great and seems to preserve all the criteria and text we've relied on, nice work.

index.html Outdated Show resolved Hide resolved
index.html Outdated Show resolved Hide resolved
Copy link
Member

@ljharb ljharb left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. If there's any of the wording in #33 that seems relevant here, that would increase the chances of obviating that PR entirely :-)

@michaelficarra
Copy link
Member Author

@ljharb I thought about it, but since I couldn't entirely obviate it (I would love to see that W3C document referenced), I decided not to go that route.

index.html Outdated Show resolved Hide resolved
index.html Outdated Show resolved Hide resolved
index.html Show resolved Hide resolved
Copy link

@bakkot bakkot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM though ideally I'd like to see something about integration with hosts, as mentioned above

@michaelficarra
Copy link
Member Author

Since the initial wave of feedback seems to have concluded, the PR has stabilised, and we've received some approvals, I've generated an updated rendering to make it easier for any further reviewers to review the current revision:

image

@ljharb
Copy link
Member

ljharb commented Jan 10, 2024

All of them have kind of a "headline" under the Purpose column except 3 and 4, should they have them too? Perhaps "Implementing and Shipping" and "Specifying and Merging" or something?

@michaelficarra
Copy link
Member Author

I figured those ones are kind of just the "headline". Stage 0 purpose also has a bit of a longer "headline" FWIW.

Copy link
Member

@littledan littledan left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is an excellent change. +1 to merging as is.

Note that I wrote related documentation at https://github.com/tc39/how-we-work/blob/main/champion.md#moving-through-the-stages-in-committee. If it becomes awkward to put too much text in this table, we can consider long-form like that. But it is certainly valuable that you ensured that this stuff is in the process document and has committee consensus, which I did not do.

Some further improvements to consider (whether in this patch or later):

  • The help text for "Purpose" is great, but I still worry about people who don't see it. Maybe the headline could be something like "Work during stage"?
  • It's great that this is framed in bullet points largely, but consider using more things to break this up visually to avoid looking like a blob of text, e.g., bold, more line breaks, spacing, etc.
  • The change removing the quotes around "champion" reminds me that we could cross-reference this with our glossary! just a thought.
  • As @ljharb suggests, some two-word summaries of what the stages mean would be valuable. I think the stage titles that you proposed would go perfectly here--including them would be consistent with the feedback from committee that numbers should remain primary, but the descriptions are still useful.

@michaelficarra
Copy link
Member Author

This has reached consensus at today's plenary.

@michaelficarra michaelficarra merged commit 9167e1e into gh-pages Feb 6, 2024
@michaelficarra michaelficarra deleted the refactoring branch February 6, 2024 18:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants