Initial Editor’s Draft of the WAC specification

csarven commented 3 years ago

After processing an ocean of documentation, issues, meetings,.. with the goal of coming up with an accurate representation of the WAC specification, this PR includes the initial Editor’s Draft (ED).

Merging this PR will replace the documentation in the README (but move its content to README-v.0.5.0), follow-up on close/respond to all applicable issues, and use the ED as the reference point.

Feedback on errors, inaccuracies, clarifications are welcome. Any request to change features or add extensions to WAC should be followed up in new or existing issues.

After the merge, the Solid Protocol will be updated to remove/update all information related to WAC. A ~Working Draft (WD) PR to the solid/specification repository will follow.

Issues/Discussions referenced:

Edit: Includes response to https://github.com/solid/specification/issues/147 and https://github.com/solid/specification/blob/main/CONTRIBUTING.md#publication-rules

csarven commented 3 years ago

@TallTed Thanks for the corrections and suggestions!

How pretentious shall we be? :) The document is not even in Latin, so maybe we should always write out "for example" and "that is"? :) Personally I find "eg. " simple/readable - am aware of the correct versions - but can live with "e.g." as that'd be properly abbreviated and consistent with BrE.

I've used lang="en" in the document but obviously en-GB-x-csarven would be better :) IMHO, it'd be great to use BrE in Solid but I don't think we should enforce this. We should just make sure each document is consistent.

As far as I know, "authorization" is allowed in BrE.

TallTed commented 3 years ago

Without any pretentiousness at all -- if either e.g. or i.e. is used, it should always be preceded by some punctuation (usually a comma, but sometimes a semicolon), and it should always be followed by a comma; these abbreviations should never start nor end a sentence. I personally find my reading jarred by ie., eg., and various other not-quite-right structures; this is part of why I tend to catch them. (I rarely use a search-replace tool for these.)

Switching to English phrasing -- whether BrE, AmE, or otherwise -- sometimes eliminates some punctuation, but usually not ... though it does tend to make the writer feel better about it.

csarven commented 3 years ago

I've updated the text to include the comma. (Prefer " eg. " over ", e.g., ", but this is not a hill..)

"e.g." followed by a comma appears to be more common than without in BrE. As far as I can tell, the last dot in "e.g." doesn't end a sentence since the dot's function is to stop the abbreviation. Attempting to end a sentence with "e.g." or even "e.g.." would be incorrect.

bblfish commented 3 years ago

The User Interface here is a bit confusing. I left a review, and I think I approved these changes, and this shows at the top right of my screen: Screen Shot 2021-06-22 at 16 44 35 But it does not show at the bottom in the reviewers that accepted the changes. I noticed that the bottom list of reviewers has a link to the review, whereas the top one does not.

TallTed commented 3 years ago

@bblfish -- A review was not requested from you, so you're not in the list of 8 "pending reviewers" at the bottom. You don't have write access on the repo, so you're not in that short list of (currently) 2 approving reviewers at the bottom. You did spontaneously submit a review, so you're in the list of "volunteer reviewers without write access" at the top. For further exploration and explanation of the Github interface, you might explore the github docs, especially Reviewing changes in pull requests.

csarven commented 3 years ago

@TallTed , after @bblfish mentioned that they didn't have access, I did request a review https://github.com/solid/web-access-control-spec/pull/83#event-4919206463 :

bblfish commented 3 years ago

Ah thanks @csarven . I thought I did get asked for a review! I noticed it today as I wanted to check up on the state of changes here.

TallTed commented 3 years ago

@csarven @bblfish -- The list at the bottom is of "pending reviewers" -- that is, people from whom a review has been explicitly requested but not yet delivered. Delivery of that requested review removes a name from the "pending" list at the bottom, and, at upper-right, changes the green dot alongside that name to a checkmark for approval, or a ± for requested changes.

TallTed commented 3 years ago

This PR is already SO HUGE, it seems long past time to close the door to further review on this PR, merge it, and perform any further review against the main branch (though it may be inspired by review of this PR).

TallTed commented 3 years ago

Of course, I've followed on my suggestion to stop accepting suggestions with another suggestion....

matthieubosquet commented 3 years ago

I think the only point worth addressing remaining in my review is the one about resources without conforming authorization: https://github.com/solid/web-access-control-spec/pull/83#discussion_r661275640

The rest of my points relate to consistent Access Control Resource discovery and I'll try to phrase a relevant issue in this repo shortly.

csarven commented 3 years ago

Thanks everyone for the reviews, feedback, emojis, etc. Merging the PR with no objections. Will follow up on issues/discussions.

Let's take a moment to congrats each other (in our minds) for getting the WAC spec to this point.

So there we have it. It is all sort of simple.

solid / web-access-control-spec

Initial Editor’s Draft of the WAC specification #83