Open chicoxyzzy opened 5 years ago
This generator sounds like a great idea! One place to discuss this would be in @ljharb's https://github.com/tc39/template-for-proposals . But, this is a rather different concept from that repository, so I would encourage you to just take a stab at implementing this in a personal repository. We would probably want to accompany this all with a strong README explaining how to use it in practice, as it may not be obvious from the TODOs (especially in setting up Travis keys, and finding ecmarkup documentation).
We would probably want to accompany this all with a strong README
Sure, I meant it, just did not mention :)
note to self:
yeoman is actually an overhead, https://github.com/SBoudrias/Inquirer.js + any template engine should be enough for simple generator which can work via npx
Just finished first version of generator https://github.com/chicoxyzzy/epgen
npx epgen
scaffolds very simple proposal template. I plan to write documentation next week
I'm not sure that this repo is the right place for such discussion, but it seems to be more suitable than other repositories. Sorry if this topic don't fit here. I think we can move it to another place in that case.
Contribution guide for ECMA262 proposes to document the problem but it doesn't tell how exactly. Looking at current proposal repos I noticed some common patterns on how proposal authors and champions organize files. Here is file structure for typical proposal repo:
I believe that template for such project could be automatically generated. I'll split these files in 3 categories.
Proposal description
README.md file is most important. Bellow I will use
[placeholder]
syntax for placeholders. Possible template for this file:This could be a nice template to start describing how proposal could be useful. Contents with markdown links and placeholders with short description of sections (not shown above) can also be generated (so they are kind of similar to GitHub's issue and pull request templates)
Spec text
All proposals use ecmarkup to generate spec text. So we need two files: package.json and spec.html. Hereinafter I'll use
[placeholder]
s as in previous section,:hyphen-case
is modifier to convert strings, for example:Proposal name
→proposal-name
.package.json
As you can see, we reuse
[proposal name]
here and add three new placeholders[author github name]
,[author name]
and[author email]
.spec.html
Template for it might look so
Now new placeholders here and again both templates are easy to autogenerate.
Deploy
To deploy proposal to gh-pages we need CI. Most of proposals in TC39 organization use Travis CI and Travis scripts have two files for deployment:
deploy.sh
and.travis.yaml
. First one is usually the same for all repos.Travis config file
We have no new placeholders here, but we need to add some instructions to configure Travis. Good thing is that this is documented already.
Summary
We can use yeoman or other generators here. To create new proposal template one should answer these questions:
After that proposal author fill proposal text, then do
npm install
,git init
and push files to GitHub. I think this will be useful for newcomers, make it easier for experienced proposal author to create new proposals and make it easier for TC39 champions for review and further editions.There should be one convention: GitHub repo name should be
proposal-[proposal name:hyphen-case]
It's also will be nice to use
npx
with yeoman to start template generator in one line (this feature is not implemented in yeoman though).Does it make sense to create such generator? I'd be happy to create it and possibly also can contribute to yeoman to add
npx
feature (if I'll have enough free time).