search

w3c / WebID

https://www.w3.org/groups/cg/webid
MIT License
14 stars 7 forks source link

Draft: revisiting the spec addressing serialization, writability, content-negotiation #15

Closed jacoscaz closed 1 year ago

jacoscaz commented 1 year ago

Better late than never, as they say!

As per https://github.com/w3c/WebID/issues/9, I've started revisiting the spec based mainly on the discussion in https://github.com/w3c/WebID/issues/3, with particular focus on comment https://github.com/w3c/WebID/issues/3#issuecomment-1279931734 which I believe summarizes a significant amount of common ground.

I've also moved some of the more technical details from the introduction to the following sections so as to keep the former as simple as possible and expand later in a more coherent manner.

This PR is still as draft but any and all preliminary feedback is more than welcome and would definitely help moving forward.

Rendered version available here

UPDATE 2023-02-16 09:19 +0100: added link to rendered version

jacoscaz commented 1 year ago

Thank you @TallTed !

TallTed commented 1 year ago

This PR does so many big things, it's very hard to review properly, even going commit-by-commit.

Is there any chance it could be redone more piecemeal, with one (mostly) or two (where they're complementary, as relocating a chunk from one section to another) of these large commits per PR?

(You might also consider skipping/undoing the "replaces markdown backticks with <code> tags", as ReSpec does the right thing with those backticks, and they make the HTML easier to read.)

bblfish commented 1 year ago

Can you provide a link to the rendered version?

jacoscaz commented 1 year ago

Can you provide a link to the rendered version?

Done - https://jacoscaz.com/WebID/spec/identity/index.html

jacoscaz commented 1 year ago

@csarven thank you for having a look and for your feedback.

i) not necessary to introduce as they appear further complicate the specification in terms of implementation as well as readability

I would be grateful if you could further elaborate on the readability issue. English is not my native language and I fully expect that there will be a significant amount of linguistic adjustments to be made. However, some of the changes I made when it comes to moving contents around (e.g. moving technical details out of the introduction and into section 5.) make the spec more readable insofar as my subjective experience goes. I'd like to understand what is making it less readable, whether it's more of a linguistic issue, a structure issue or something else entirely.

ii) not based on consensus decisions, especially when there are notably different preferred solutions on record. Proposed changes can also be better backed by showing implementation feedback, reports, surveys, or even intention to implement.

I will update the PR's description with links to the relevant posts, emails and implementations.

I agree with the others that there is too much going on in this PR.

Although I agree that this is a big PR, I don't think I can break it down in a manner that effectively achieves the same goal. I would not be able to keep track of discussion splintering across multiple PRs affecting one another.

Is there anything I can do to facilitate diffing the two beyond splitting into multiple PRs? I've been looking for a content-based diffing tool but, to my surprise, I wasn't able to find anything.

jacoscaz commented 1 year ago

This PR does so many big things, it's very hard to review properly, even going commit-by-commit.

Is there any chance it could be redone more piecemeal, with one (mostly) or two (where they're complementary, as relocating a chunk from one section to another) of these large commits per PR?

@TallTed similarly to my response to @csarven , I don't think I'd be able to do this across multiple PRs, particularly given that the issues I address affect one another as demonstrated by the discussion in #3 (amongst others). Can you think of something I could do to help with revising this PR other than splitting it across multiple ones?

langsamu commented 1 year ago

As an implementer of this specification I am very interested in proposed changes.

Unfortunately I am not able to engage with this change set due to reasons others mentioned. This stops me from assessing its impcat and providing feedback.

jacoscaz commented 1 year ago

I have had significantly less time than I had expected to work on this and, given interest levels and ongoing conversations, it feels right to close this PR and leave the floor to a more conservative path forward (see https://github.com/solid/solid-wg-charter/issues/39).