-
Notifications
You must be signed in to change notification settings - Fork 18
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
Conversation
There was a problem hiding this 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.
There was a problem hiding this 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 :-)
@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. |
Co-authored-by: Chris de Almeida <[email protected]>
There was a problem hiding this 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
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? |
I figured those ones are kind of just the "headline". Stage 0 purpose also has a bit of a longer "headline" FWIW. |
There was a problem hiding this 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.
This has reached consensus at today's plenary. |
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:
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:
Ping @waldemarhorwat since he asked to be notified when I opened this PR.