`spec.html` vs `index.html` when detecting whether proposal repo has spec

[DerekNonGeneric]

The hasSpec predicate of our info crawler (currently still in draft form for various reasons) determines whether a proposal has a spec by checking if the repo files listed by the GitHub API contains a file named spec.html at the root of the source tree. This template, however, appears to be placing the generated output of “fixup: [spec] npm run build” commits in a file named index.html on the repo default branch.

Since it is expected for the generated spec file to ultimately live at index.html on the gh-pages branch, would it be possible to convince you all to make the generated spec file that lives on the repo default branch be i) named spec.html and ii) continue to be located at the root of the source tree?

From what I gather, that appears to be the convention that has been followed historically and wonder if the proposal repos generated by this template break from this convention. Either way, we still need a reliable way to detect whether a proposal has a specification or not, so any suggestions here would be appreciated.

[ljharb]

I don’t think that is expected. Every proposal repo is allowed to do whatever bespoke thing it wants; the template explicitly expects an index.html file on the default branch (no gh-pages branch at all).

Thus, there is no convention, and no reliable way short of “it’s probably the only html file checked into the repo”.

[DerekNonGeneric]

That is problematic because proposal repos generated using this template already contain an html file — a specification document even (although mostly blank) — right out of the box, so we would need to parse the contents of every html file on the default branch before being able to know if a proposal repo contains specification content that would be of any real value to assist our predicate in determining whether a proposal has a spec or not. If a better way is known, it would be really nice to know what that might be.

[ljharb]

I'm not sure how to help. Even if the template picked a convention that worked for you, the committee has been very resistant to proscribing things about the way proposal repos are constructed, so I think the goal is unachievable.

[DerekNonGeneric]

Perhaps the proposal repo metadata file discussed in the https://github.com/tc39/dataset issues should have a boolean-value field that proposal authors can flip once they feel they have contributed a specification worthy of committee review.

[DerekNonGeneric]

Unbelievably MDN just published a new notecard ~13 hrs ago for displaying the result of a query exactly as I describe above.

⚠ No specification found

See: https://github.com/mdn/yari/blob/HEAD/client/src/document/ingredients/spec-section.tsx

I imagine they will be making a similar request in the very near future.

Although my intended method for detection may be unreliable, this issue should probably be interpreted as a feature request of sorts, so I will leave this open for a bit longer to give others a chance to chime in and, if you don't mind, keep it open for as long as it takes for us find a solution to this problem.

[ljharb]

The answer would still be the same - it'll have to be manual, since we almost certainly won't find consensus for mandating anything about proposal repo structure.

[DerekNonGeneric]

This must be a new feature, but if a proposal repo has GitHub Pages enabled for repo default branch, a rendered view of that proposal's explainer (normally located at README.md) becomes available at https://tc39.github.io/proposal-lorem-ipsum/ unless the repo contains index.html (in which case it gets overridden to use that instead).

+1 to having the spec available at spec.html.

It still wouldn't provide any guarantees beneficial to our predicate in making a determination about the presence of a viable spec, but at least it would mean that a rendered view of both the explainer text && the spec text would be available for inspection in separate locations and both would be free of the GitHub UI & branding (looks more vendor-neutral to those who care).

[ljharb]

That’s not accurate; each repo has its own settings for GitHub pages. The options are a gh-pages branch, the root of the default branch, or /docs in the default branch. In all cases, without exception, the file would be named index.html - never spec.html.

[DerekNonGeneric]

Okay, thanks. I will let you know once the explainer text is presentable.

[DerekNonGeneric]

Although my intended method for detection may be unreliable, this issue should probably be interpreted as a feature request of sorts, so I will leave this open for a bit longer to give others a chance to chime in and, if you don't mind, keep it open for as long as it takes for us find a solution to this problem.

Whoops, closed too soon.

[ljharb]

closing since this seems answered, but can reopen if needed.