Skip to content
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

Meta: Add proposals/ folder #108

Merged
merged 8 commits into from
Apr 20, 2023
Merged

Meta: Add proposals/ folder #108

merged 8 commits into from
Apr 20, 2023

Conversation

a-sully
Copy link
Collaborator

@a-sully a-sully commented Apr 3, 2023

It's an open question as to where explainers related to this specification should live. With a handful of explainers in existence and a number more in the works, it would be nice to establish a pattern for where these documents should live.

The current pattern of creating un-merged PRs not sustainable. See w3ctag/design-reviews#805 (comment)

The most common options seem to be (see some previous discussion #46 (comment)):

  • Posting explainers to personal forks (this seems to be the most common pattern)
    • Pros:
      • The upstream repo remains uncluttered
    • Cons:
      • This can lead to broken links (e.g. Iframe credentialless (WIP) storage#139)
      • While the spec provides the how and the what, it can be quite challenging to trace the paper trail of why the spec is the way it is, especially if explainers are coming from a variety of contributors
  • Posting explainers into the specification directly into the spec repo
    • Pros:
      • Easily find all the explainers related to a specification
    • Cons:
      • The root of the spec can become quite cluttered if you have a lot of explainers
      • It can lead to the anti-pattern of putting the useful text only in the explainers and not in the spec text itself

This PR proposes a new option: Posting explainers into an explainers/ folder in the spec repo

As a fairly new specification, there are a known, small(ish) number of explainers such that it's not hard to aggregate them for now (with some more in https://github.com/WICG/file-system-access that we may want to consider porting parts of over eventually). But this spec has lots of room to grow, and I expect a number of explainers coming in the near future. I personally think it would be nice (and I suspect others, such as those providing TAG reviews, might agree) to have all these explainers in an easy-to-find location, without cluttering the spec repo too much

This PR merges the following explainers:

#46 is not merged for now, as to not lose the discussions on that PR already

cc @torgo

@a-sully
Copy link
Collaborator Author

a-sully commented Apr 4, 2023

@annevk @domenic does this approach seem reasonable?

@domenic
Copy link
Member

domenic commented Apr 4, 2023

Yes, this seems reasonable to me. As I noted previously, I think explainer organization should be up to the editors, e.g. in whatwg/streams we've put them in the root, whereas for many of @annevk's specs he's preferred leaving them in other repos.

@annevk
Copy link
Member

annevk commented Apr 5, 2023

I think the problem I have with them is that they are quite official-looking and people might mistake them for WHATWG-endorsed ideas.

@a-sully
Copy link
Collaborator Author

a-sully commented Apr 6, 2023

Fair point, though personally I think I'd still prefer to have all these proposals in one place. There are some nice benefits to this organization (e.g. the timeline of feature additions, and why features were developed, is much easier to trace and therefore much more transparent) and I think we can mitigate the risks you mentioned by presenting these in a less official-sounding way.

In that vein, I've renamed this folder to proposals/, which I think better conveys what these documents are anyways

@a-sully a-sully changed the title Add explainers/ folder Add proposals/ folder Apr 18, 2023
@annevk
Copy link
Member

annevk commented Apr 20, 2023

I think that still doesn't really convey their insignificance to the WHATWG process. It seems better to keep them out-of-band.

@domenic
Copy link
Member

domenic commented Apr 20, 2023

Perhaps a README.md in the subdirectory could help assuage @annevk's concerns.

Copy link
Member

@annevk annevk left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On further consideration we only publish official WHATWG stuff on whatwg.org so I guess this is okay for now. Hopefully in due course we'll have a better way to deal with proposals/ideas.

@annevk
Copy link
Member

annevk commented Apr 20, 2023

Please do use a "Meta:" prefix when landing this as it's not part of the standard and so shouldn't really impact its commit log.

@a-sully a-sully changed the title Add proposals/ folder Meta: Add proposals/ folder Apr 20, 2023
@a-sully a-sully merged commit 8360b75 into whatwg:main Apr 20, 2023
@a-sully a-sully deleted the explainers branch April 20, 2023 14:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Development

Successfully merging this pull request may close these issues.

3 participants