Repository navigation
Which documents are working copies and which static snapshots? #389
Description
Looking at the current layout of the repo:
/seems to have the latest version of what appears under/TR/ecosysteminterestingly showsEDstatuswachas uniqueDraftstatus
EDseems to have haveprotocolcopy withEDstatus- once again
EDof ecosystem stays in the/
- once again
2021soon2022seem to have snapshotsprotocolsnapshot hasEDstatuswacagain has uniqueDraftstatus
I find this layout somehow confusing, looking at some PR with Protocol label they target /protocol.html (in the / so /TR/). This makes me wonder what is the purpose of /ED/protocol.html.
Once other drafts start adding read-only snapshots to this repo #386 situation may get even more confusing if someone ends sub making PR on a document intended to be a read-only snapshot eg. /oidc.html
At a minimum, I believe this repository should make it clear which documents are working copies and which read-only snapshots. As I suggested in #388 (comment)
Possibly even better would be to only keep ED in this repository and move ecosystem there as well. All the read-only snapshots could be aggregated in the dedicated repository which would make clear that it doesn't accept any editorial PRs.
Activity
kjetilk commentedon Mar 30, 2022
Yeah, it is very confusing, and it is like having a poor-man's version control within a rich version control system. The plan, and it is pretty near term, is to migrate solidproject.org to CSS and then use tags to mechanise deployment #370 (and links from there), so we don't need to have copies in the repo at all.
csarven commentedon Mar 30, 2022
Interesting. The URL convention is adopted from W3C's ;)
elf-pavlik commentedon Mar 30, 2022
This issue wasn't about URL conventions. @kjetilk comment addressed it well, I understand that the current situation is a temporary state which will change once #370 gets resolved.
csarven commentedon Mar 30, 2022
The reason I've mentioned the URL convention is to shed light on the current directory structure.
Background: I don't have a strong preference on the repo/branch/tagging organisation/convention. Ultimately I care about the URIs under solidproject.org. As for repo organisation, I've proposed what I've done in the past as per W3C's suggestion at https://github.com/w3c/ldn but IIRC we didn't end up taking that approach for {reasons}. I've also proposed/used briefly the editors-draft branch but we also didn't continue on that. I've re-proposed (pushed strongly) to make sure we run the whole website off a Solid server (for dogfooding reasons...) - see my PROPOSALs in minutes and ACTIONs - and we are pretty close to having that going, which is great and exciting. And I've also introduced the notion of persistent URIs backed with a policy (see the website), and again, based off W3C's. FWIW.
Most important layout is already mentioned in the README and with a bit more detail on the CONTRIBUTING that I've proposed:
/TR/yyyy/ is intended to be immutable and persistent - with rare exceptions to update (something that W3C also does).
Directly under /TR/ and /ED/ are intended to be mutable.
There are discussions at W3C about URI ownership with regards to what's under github.io/com and w3.org. I've pushed for /ED/protocol to be under solidproject.org as opposed to solid.github.io/specification/protocol with also those discussions in mind. Besides, solidproject.org looks cooler when hosted from a Solid server.
It is possible that all CG's ED could be published under ED/.... we'll come back to that.
That was deemed to be the simplest mapping we could do and publish based on the machinery/human effort we have.
This document originally held the Protocol spec's content but then it was put aside. It still has ED status because we didn't continue to work on it. And, it also predates the /ED/ . This document may be removed. I've discussed it elsewhere...
It is not that unique. It was intended as a ~WD at the time but as I've suggested that our CG documents shouldn't strongly communicate using terminology from W3C Rec track, I just dropped the "Working" bit. We are not strictly doing CG-DRAFT and CG-FINAL either...
ED/ is intended for documents that will have the ED status - living document of sorts. Surprise! And, no, it is not a copy of the protocol. protocol is derived from the ED for the most part with changes to the status, links, dates, and some other stuff.
Once again, we'll see if/where ecosystem will live. It could move to ED/ecosystem and also have TR/ecosystem. We might only have TR/ecosystem and update.
Once again you're mistaken about "snapshot"s and the statuses used. Check out some W3C specs and see how the documents: this version, latest published version, previous version, latest editor's draft, and so forth are related/linked.
Everyone had plenty of time to chime in about all of these things in the past. Here is to making things better.