add a reviewers column in stage 2 table

[michaelficarra]

We (are supposed to) assign reviewers to proposals as they move from stage 1 to stage 2. In order for a proposal to advance to stage 3, these reviewers must sign off on the spec text. We sometimes forget to assign reviewers, and sometimes forget who we assigned. This column will help us keep track of that.

On a related note, does anyone know who was supposed to review the function implementation hiding proposal? I couldn't find anything in the notes.

[ljharb]

That seems like a great idea.

Re reviewers: https://github.com/tc39/tc39-notes/blob/c4466ea1977d17a0fa607e3ab9ff63504dba004f/meetings/2019-03/mar-27.md#conclusionresolution

[chicoxyzzy]

Wouldn't it be better to link to Stage 3 reviews issue in proposal repo instead of adding (and possibly changing) names?

[ljharb]

It’d be more concise; but the names are a requirement, a reviews issue is not.

[septs]

i think, we need normalize structured metadata and structured this repo
(but need normalize proposal README file writing method)

use data drive, nightly build new gh-pages (searchable, sortable)
and provide structured data set to any user (e.q: https://tc39.es official site)

like https://jekyllrb.com/docs/front-matter/

CC @codehag and @TechQuery

[codehag]

We might be able to take inspiration from w3c here. I spoke with Derek about it on tc39.es, and I was thinking of proposing it at our upcoming meeting. In the case of w3c, source of truth is the repository. In our case, it has been convenient that we can just update here, but maybe changing our working method is a good idea.

[septs]

@codehag We need a proposal for normalize proposal and normalize agendas.

if normalize agendas markdown metadata then we can get available meeting calendar. (provide for tc39.es)

automate tracking #140 changes becomes possible (follow specific issue is closed, etc)

[codehag]

I might be misunderstanding what you mean by normalize? Maybe what you mean is a template proposal? Or something else?

For proposals, we have this template: https://github.com/tc39/template-for-proposals
And for agendas: https://github.com/tc39/agendas/blob/master/template.md

[septs]

no, no, no, provide a metadata on markdown

see like https://jekyllrb.com/docs/front-matter/

preview: https://github.com/mattvh/jekyllthemes/blob/master/_posts/2013-06-01-scribble.markdown

i think, program readable (parsable) very important

or

add a specific file to repo (stable structure yaml/json file, it is metadata)

[ljharb]

The repository should always be the source of truth; I'm not sure what "working method" change is being referred to.

We could certainly put the proposal data in a machine-readable format, and auto-generate the markdown files, but it's difficult to do that ergonomically and still allow edits on the web interface.

[codehag]

Ah, I see. Thanks for the clarification @septs -- yes this was what I was thinking also. w3c uses structured JSON files for that. We wouldn't need the same fields but the idea might apply.

@ljharb yeah I had a feeling that might be the reaction to introducing w3c's json files to individual repositories or something similar. I would like to find a way to extract all proposal data in an easy to read from a machine perspective, but its a bit hard to come up with an idea. If we did the w3c thing, we would need to be pretty rigorous about how we update proposals, and it would be more time intensive than it is now (where we can update this repository). If a given proposal repository is out of date it isn't such a big deal with our current process. If we start using automated generation, a given proposal repo might get out of date, and then our proposals directory repository (that is, this current issue tracker's proposal) will get out of date. I have the same concern. That said, we might be able to apply this to this repository somehow, maybe?

I am open to ideas though, maybe we should explore this space and see what can be done?

Edited for clarity.

[ljharb]

I'm also open to ideas! So far all I've thought of (that wouldn't result in a very messy default branch) is using github actions to aggressively rewrite PRs prior to them being merged to ensure that the generated content is always up to date, but that can easily cause race conditions when the PR author is trying to make changes while the action is trying to do so as well.

[codehag]

Oh, that is pretty interesting. So that would be a pull request hook that would validate the pr. One way to address the race condition is by causing the job to fail if something is out of date, and that would give the author a signal of what needs to change. We should be able to output an error message for that.

Alternatively, this could be something run on the authors machine as a linting step -- I think its a push hook? Then we don't need to worry about github action limits.

[septs]

if maybe we can contact github support, provide a api get use for https://github.com/tc39/template-for-proposals template repos.

automate discovery new proposal and automate follow it.

[codehag]

I think, we don't want to automatically track all repos that are made from that template -- not everything is necessarily accepted to stage 1, or even ever presented. This might result in a lot of noise...

Though it would be interesting. we would see what people are playing with.

[ljharb]

@codehag unfortunately git hooks are not reliable; they're always bypassable on the client, and git does not allow them to be automatically provided by a repo for security reasons (although there are tools that ignore those security reasons and auto-install hooks, but I would strongly advise against using one of those).

[ljharb]

@septs repos are not required to use the template, only encouraged, so that list wouldn't be complete.

[septs]

Then we don't need to worry about github action limits.

open ticket on github support. unlimit for tc39 local gh-action? (in dreaming)

[codehag]

@ljharb I think that might be a polish step -- Having it work perfectly locally isn't necessary, we can have a ci step that verifies it. For adding the tooling, I believe the work flow is to create the file that can be used in the hook and have it in the repo (but not in .githooks), and then explain in the readme how to use it, rather than automatically providing it. This way the user can choose to use it if they wish, and if they don't they might get an angry ci error.

Anyway, its only one option. I am sure there are others. We might want to get together some requirements to help us understand what this needs to be.

[septs]

add a specific file to repo (stable structure yaml/json file, it is metadata)

if use json file format, we can use json-schema linter its.

{
    "$schema": "https://tc39.es/schema/metadata.json",
    "name": "foo",
    "stage": -1,
    // etc
}

other ideas:

• provide proposal design usage sample code and code comment in specific file (sample-code.js ?)

---

major IDEs/Editor provide good type hints (automate read JSON Schema definition and hint field name, etc)

[csvn]

YAML might be slightly more human readable/writable in general, if that is a priority. YAML can also be linted/validated with JSON schemas as well.

[ljharb]

Anything but YAML; TOML at least if we're going that route. JSON seems like the most straightforward choice, and is sufficiently human readable/writable.

[csvn]

Sorry, wasn't trying to steer the discussion into this direction. I just find JSON to be the most annoying of common data formats to edit (compared to TOML, YAML, .gitignore, etc), though with it's widespread use it's a safe choice. I have no idea of tooling support for linting/validation of TOML files.

[septs]

Sorry, I confuse normalize and standardize. (errata)
Plz replace normalize to standardize, thanks.