search

tc39 / js-outreach-groups

62 stars 7 forks source link

Generator for ECMAScript proposals templates #3

Open chicoxyzzy opened 5 years ago

chicoxyzzy commented 5 years ago

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:

.travis.yml
deploy.sh
package.json
README.md
spec.html

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:

# [proposal name]

[author name]
Stage: pre-proposal (?)

## Contents
1. Introduction / Description
2. Motivation / Problem
3. Examples
4. Polyfill (if exists)
5. Potential issues and open questions
6. FAQ

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

{
  "private": true,
  "name": "proposal-[proposal name:hyphen-case]",
  "version": "1.0.0",
  "description": "ECMAScript [proposal name] proposal",
  "repository": "[author github name]/proposal-[proposal name:hyphen-case]",
  "author": "[author name] <[author email]>",
  "license": "SEE LICENSE IN https://tc39.github.io/ecma262/#sec-copyright-and-software-license",
  "homepage": "https://[author github name].github.io/proposal-[proposal name:hyphen-case]/",
  "dependencies": {
    "ecmarkup": "^3.12.0"
  },
  "devDependencies": {
    "@alrra/travis-scripts": "^3.0.0"
  }
}

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

<pre class="metadata">
title: [proposal name]
status: proposal
stage: 0
location: https://github.com/[author github name]/proposal-[proposal-name:hyphen-case]
copyright: false
contributors: [author name]
</pre>

<emu-intro id="intro">
  <h1>Introduction</h1>
  <p>TODO: add introduction text</p>
</emu-intro>

<emu-clause>
  TODO: add spec text
</emu-clause>

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

sudo: off

language: node_js

node_js:
  - "node"

script:
  - bash ./deploy.sh

env:
  global:
    - ENCRYPTION_LABEL: TODO add encryption label here
    - GH_USER_NAME: "[author github name]"
    - GH_USER_EMAIL: "[author email]"
    - PRIVATE_KEY_FILE_NAME: "github_deploy_key.enc"

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).

littledan commented 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).

chicoxyzzy commented 5 years ago

We would probably want to accompany this all with a strong README

Sure, I meant it, just did not mention :)

chicoxyzzy commented 5 years ago

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

chicoxyzzy commented 5 years ago

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