Specification repo should not be top-listed on solid org

[kjetilk]

Currently, the https://github.com/solid/specification repository is top-listed amongst the six most exposed repositories. I think it should't be, as it is not the normative specification, and this creates an expectation that it is. The specification is essentially a draft, work in progress by a panel, and should not have that kind of exposure.

[Mitzi-Laszlo]

A very similar conversation was also covered on the W3C Solid Community Group call on the 1st August and discussed on solid/solid-spec on the same day.

Let's use the last paragraph of the drafting proposals part of the process to come to a solution.

The question is: Which repository of Solid GitHub is the normative specification where proposals in the form of pull requests should be submitted to? and what should be done with repositories that could be considered confusing to avoid confusion?

The next step is for everyone to write each option to solve this question as a separate message.

If you approve an option put a thumbs up, if you disapprove an option put a thumbs down.

The outcome of this process is not binding, it is just consultative.

[maxidorius]

Which repository of Solid GitHub is the normative specification where proposals in the form of pull requests should be submitted to? and what should be done with repositories that could be considered confusing to avoid confusion?

I think this question doesn't really make sense. From previous discussions and from the specification repository itself, we already know that:

• We want to keep to the orthogonality principle, meaning there will never be one single repository
• The point is to have an entry point, a gateway to the spec documents themselves. The current repository is designed that way.

So I don't think it's a question of the specification repository being the wrong choice: it's just the only choice to have a landing point for anyone wanting to deal with the Solid spec, whatever "spec" mean. It should be easy for people to find a single repository from where they will find all they need.

I think it should't be, as it is not the normative specification, and this creates an expectation that it is. The specification is essentially a draft, work in progress by a panel, and should not have that kind of exposure.

Now for the fact that the repository is incomplete, let's just complete it, or at least have a basic README that links to all the other repository. We don't necessarily need the final product - this is always a work in progress. By having this landing repository as early as possible, we also give the chance to the community to report how well that is working for them. Not having a repository at all doesn't help anyone and does not trigger improvement. We just stay in the same tribal knowledge as before and it makes it very hard for newcomers to get started. Being a newcomer myself, I can definitely tell you a landing repository, whatever it is, is more than welcome, even if incomplete.

Bottom line is: We should focus the discussion on actually improving the documents, and not yet discuss the form around it. It's a bit too early in my opinion to do so.

[Mitzi-Laszlo]

@maxidorius does this question make sense to you?

Which repository of Solid GitHub is the normative specification where proposals in the form of pull requests should be submitted to?

If not, what question do you think gets the the bottom of the conversations?

[maxidorius]

So I thought about it, and the question doesn't really make sense either. There isn't a single repository.

To get at the bottom of this, I have one question for @kjetilk: Is that specific repo the issue for you, or the fact that there is a single "landing" repo?

[kjetilk]

I think we are discussing a long range of issues now.

First, we need to agree on the short-term goal of the current specification rewrite: It is not to add new features, but rather to document the current state of the art in a way that adds clarity and rigor, so that the conformance criteria becomes clear from the specifications itself, and so that we can have a test-suite that can be used to verify that you have a conformant implementation.

Therefore, proposals to alter the semantics of the normative specifications is something I don't think we are ready to process before we have the current state of the art properly specified. Until the state of the art is properly specified, the solid-spec repo remains the source for normative specifications, and should be the one that is promoted. So, to your last question, @maxidorius neither of those are my concern, my concern is that specifications is not the normative source yet.

But this also means that we have a point in time when retirement of solid-spec, readiness to process new proposals and finishing of test suite coincides with the readiness of the rewritten specifications. Whether new submissions should go to the solid-spec or the specifications is a matter where I don't have very strong opinions. I think my preference would be "take it easy, do work in panels, and then submit when we have the spec rewrite ready" :-)

To me, the orthogonality principle is also very important,  @maxidorius . However, I don't see it as very important that each orthogonal specification resides in a repo of its own in the context of Solid.

Orthogonal specifications is important to ensure independent evolution, and there are many examples where when it hasn't been maintained, it has created problems. OTOH, orthogonality also makes understanding a whole system more difficult, and so, I think it is important to document all of Solid in a consistent way. It is then important, IMHO, that we can tell the difference between specifications and other documentation.

Solid consists of many orthogonal specifications, where we would essentially just tie them together, sometimes add more stringent conformance criteria (e.g. a MUST where the original spec had a SHOULD). We also add specifications that, even though they may have existed for some time, will be more rigorously defined by the Solid project, such as WAC. They fall into the category of orthogonal specifications, in that they can (and hopefully will) find reuse beyond Solid.

However, when it comes to answering "what is Solid?" in terms of specifications, that question is probably best answered by pointing at a specification where several orthogonal specifications are tied together by a document that is not orthogonal to everything else. @timbl did actually warn against taking the orthogonality principle too far, sometimes, you need to provide a consistent whole for interoperability.

Then, what remains to be seen is whether that document will consist of normative statements and so will rightfully be called a specification or whether that will be merely project documentation.

But all this is really orthogonal [sic!] to whether the specification repo should be top-listed on solid org, the essence of that issue is that the specification repo is not yet normative, and requires much work to get there.

[maxidorius]

Ok, so am I to understand you would be happy to have https://github.com/solid/solid-spec replacing the currently pinned specification repository? In my view, it makes no difference which repository is pinned for this, just that one is regarding the specification.

[kjetilk]

Ok, so am I to understand you would be happy to have https://github.com/solid/solid-spec replacing the currently pinned specification repository?

Yes, I think that would be preferable.

[justinwb]

I agree with @kjetilk's original point, and I think that's where we've arrived in the end on this thread. Unless there's any strong disagreement, I think we should do the following:

1. Update the README at https://github.com/solid/solid-spec with language that explains we're in the process of creating a more comprehensive and robust version of the specification at https://github.com/solid/specification.
2. Update the pin with https://github.com/solid/solid-spec until we achieve (at a minimum) parity from https://github.com/solid/specification

[csarven]

I agree with the above on clarifying the differences between the repositories and as well as the change to pinned repository for the spec (solid/solid-spec) along with the location to current/ongoing/future spec repo (solid/specification). Provided that pinned repo location will be updated later.

---

The work in solid/solid-spec is considered to be a draft, and predates the Solid CG as well as the process here. As the Solid spec (in solid/specification) is carried out under Solid CG, solid/solid-spec content should only be acknowledged as an "Unofficial Draft" (UD). Within the context of the CG, the initial publication of the spec is analogous to W3C's "First Public Working Draft" (FPWD) but without any official acknowledgement from W3C.

There is no need to make a mass copy of content or issues from one repository to another. There are many links from solid/specifications issues to solid/solid-spec issues and documentation acknowledging the work and carrying it forward. Some issues/discussion deemed to be significant and useful was migrated (and still can where appropriate).

[csarven]

Status update:

The Solid CG agreed with the proposal above ( #100 (comment) ): https://www.w3.org/community/solid/wiki/Meetings#20200109_1000CET

It is now reflected in:

• solid/specification@f2eeb0a
• Pending: Added Publication Status solid-spec#215
• Pending: Updated information pertaining to pinned repository. Issue #100 #187

[csarven]

Closing this issue as solid/solid-spec#215 and #187 are now merged.