Which documents are working copies and which static snapshots?

[elf-pavlik]

Looking at the current layout of the repo:

• / seems to have the latest version of what appears under /TR/
  • ecosystem interestingly shows ED status
  • wac has unique Draft status
• ED seems to have have protocol copy with ED status
  • once again ED of ecosystem stays in the /
• 2021 soon 2022 seem to have snapshots
  • protocol snapshot has ED status
  • wac again has unique Draft status

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.

[kjetilk]

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]

Interesting. The URL convention is adopted from W3C's ;)

[elf-pavlik]

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]

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.

---

/ seems to have the latest version of what appears under /TR/

That was deemed to be the simplest mapping we could do and publish based on the machinery/human effort we have.

ecosystem interestingly shows ED status

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...

wac has unique Draft status

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 seems to have have protocol copy with ED status

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 ED of ecosystem stays in the /

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.

2021 soon 2022 seem to have snapshots
protocol snapshot has ED status
wac again has unique Draft status

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.