specification
specification copied to clipboard
solid
Please review CG Report requirements
Hi all,
In looking at a sample Solid technical report such as: https://solidproject.org/TR/protocol
I would like to draw the CG's attention to our CG Report requirements: https://www.w3.org/community/reports/reqs/
Among them notably, we have style requirements (to help people understand the status of documents) and copyright statement requirements (per the CG policies), etc.
I'd like to request that the CG make appropriate changes based on these requirements. Don't hesitate to contact me on team-community-process if you have questions.
Cheers, Ian
[1] https://www.w3.org/community/about/process/summary/
@csarven, once the reports have been reformatted, it would be great to register them in the W3C CG Report system by way of the "publish" button that appears on the CG's home page when you are (1) logged in and (2) chair of a CG. For more, see: https://www.w3.org/community/about/faq/#how-do-we-publish-a-report
Thanks!
Thanks @ianbjacobs ! Am/we're aware.
Short response: Going forward, the CG will produce CG-DRAFT/FINAL reports as you recommend as well as per Solid CG charter.
Longer response:
The latest published versions (what you see published under solidproject.org/TR/ ) and the deliverables referred by the proposed Solid WG charter have been using the Solid Process (which is no longer applicable to the CG). This is only one part of the reason why Solid CG hasn't produced a CG-DRAFT/FINAL. Going forward, the CG will follow its CG charter (became effective 2023-09-01), which is aligned with W3C's processes and recommendations.
To the best of Solid CG's and W3C contacts' ( @pchampin @rigow ) knowledge:
- Report Requirements is acknowledged, however CGs are not prohibited from producing documents that are not CG-DRAFT/FINAL, with any status, license, at any location, or using any particular stylesheets/scripts (=we're aware that they're not or equivalent to W3C "Community Submissions").
- Deliverables of a WG charter or proposed specifications are not required to have a CG-DRAFT/FINAL status in order for them to be accepted as part of a WG charter proposal and followed-up in Recommendation/Note/Registry Tracks. There is no mention in, e.g., W3C Process or W3C Recommendation Track Readiness Best Practices. On a related note, the common understanding is that a "Working Group will not adopt new proposals until they have matured through the [CG] or another similar incubation phase.". This seems to be satisfactory for Solid CG's work items, i.e., without CG-DRAFT/FINAL status, being picked up by a WG charter.
- We have taken steps to make sure that copyright/licensing in the CG charter will remain compatible with W3C policies and have acknowledged that agreements made through CG-DRAFT/FINALs will better help to transition works from the CG to a WG.
Happy to be corrected on anything above. And happy to hear any additional insights you can offer.
Again, happy to produce CG-DRAFT/FINALs (in particular proposed deliverables of the WG charter) and follow up with the publication process.
We will also follow-up with updating CG's Contributing Guide to reflect any remaining changes related to publication of documents/reports.
Lastly, I understand the differences between what can be practised, required, or prohibited by W3C in a CG (and elsewhere) may be confusing to some or even many. I can only recommend that existing CG requirements, W3C Process, and other guides are updated to further help minimise these confusions for anyone, and to better communicate expectations. If you'd like me/us to follow-up on this with you / W3C Team in another thread/repository, happy to do so.
Hi @csarven,
CGs are not prohibited from producing documents that are not CG-DRAFT/FINAL, with any status, license, at any location, or using any particular stylesheets/scripts (=we're aware that they're not or equivalent to W3C "Community Submissions").
That is also my understanding.
Deliverables of a WG charter or proposed specifications are not required to have a CG-DRAFT/FINAL status in order for them to be accepted in Recommendation/Note/Registry Tracks.
That is also my understanding (but not directly relevant to the current thread about CG Report requirements).
On a related note, the common understanding is that a "Working Group will not adopt new proposals until they have matured through the [CG] or another similar incubation phase.".
Here is what the Advisory Board wrote in 2016 [1] on that topic: "Strongly Recommended: Charters do not list specs as deliverables, and WGs do not publish FWPDs, until there is rough consensus across stakeholders that the spec solves a real problem, is likely to be implemented, and is likely to be used on the Web. This consensus could emerge from an incubation phase in WICG or another CG, or in a WG that has an established culture of taking and vetting suggestions from its public mailing list."
[1] https://www.w3.org/Guide/standards-track/#criteria
We have taken steps to make sure that copyright/licensing in the CG charter will remain compatible with W3C policies and have acknowledged that agreements made through CG-DRAFT/FINALs will better help to transition works from the CG to a WG.
Our FAQ [2] includes this:
Q. Can I make it a condition of joining a Community or Business Group or publishing a Report that people must agree to licensing terms beyond the CLA/FSA? A. No.
Is the expectation that people cannot join the Solid CG unless they agree to the terms and conditions of the charter?
[2] https://www.w3.org/community/about/faq/#can-i-make-it-a-condition-of-participation-in-a-community-or-business-group-that-people-must-agree-to-licensing-terms-beyond-the-clafsa
Lastly, I understand the differences between what can be practised, required, or prohibited by W3C in a CG (and elsewhere) may be confusing to some or even many. I can only recommend that existing CG requirements, W3C Process, and other guides are updated to further help minimise these confusions for anyone, and to better communicate expectations. If you'd like me/us to follow-up on this with you / W3C Team in another thread/repository, happy to do so.
We welcome suggestions on [email protected]. Thank you!
@ianbjacobs the list of draft reports I filled in on https://www.w3.org/community/solid/ during our meeting today was a copy of https://solidproject.org/TR/#work-items
But since then I got a message from @VirginiaBalseiro saying this list is incorrect and not conforming to https://www.w3.org/community/reports/reqs/. I was also unaware that this had been an open issue since October.
As we discussed there is an 'add' button but no 'remove' button. Can you please remove the list again? Sorry for the hassle!
I will PR a CG-DRAFT (and eventually FINAL) of the Solid Protocol based on ED. I have the CG-DRAFT ready but was waiting on the possible resolution of some of the items in the last milestone if the Group deemed them to be ready. There is no showstopper to have a CG-DRAFT of what we have, and I think we can go ahead with it. I can PR in the next week or so (keeping in mind travels). We (CG) can perhaps pick it up on 2024-05-08 ( @VirginiaBalseiro ).
We can publish other Work Items as CG-DRAFT/FINALs once they're ready and agreed upon.
Hi all,
If these are indeed reports of the CG, then it is important that they adhere to the CG report requirements [1], including the copyright statement, use of logos, boilerplate text, etc. Let me know how I can help on this.
Regarding the link from the CG’s home page, I think we can leave them in place since the more important bit is that the spec styles be updated. (And I’m assuming the URLs will point at the updated drafts.)
Thank you,
Ian
[1] https://www.w3.org/community/reports/reqs/ [2] https://www.w3.org/community/solid/
On Apr 25, 2024, at 9:57 AM, Sarven Capadisli @.***> wrote:
I will PR a CG-DRAFT (and eventually FINAL) of the Solid Protocol based on ED. I have the CG-DRAFT ready but was waiting on the possible resolution of some of the items in the last milestone if the Group wanted them in there. There is no showstopper to have a CG-DRAFT of what we have, and we can go ahead with it. I can PR next in the week or so (keeping in mind travels). We (CG) can perhaps pick it up on 2024-05-08. We can publish other Work Items as CG-DRAFT/FINALs once they're ready and agreed upon. — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you were mentioned.Message ID: @.***>
-- Ian Jacobs @.***> https://www.w3.org/People/Jacobs/ Tel: +1 917 450 8783
@ianbjacobs the list of draft reports I filled in on https://www.w3.org/community/solid/ during our meeting today was a copy of https://solidproject.org/TR/#work-items
@michielbdejong can you clarify what "our meeting" is referring to?
@ianbjacobs I think we already covered this earlier in the issue and elsewhere.
Just for clarity for those not heavily involved in the CG or who need a summary:
Our process prior to the Solid CG Charter didn't include publishing W3C CG Reports. The documents that are currently referenced from Solid Work Items are not "W3C CG Reports" as it stands but we're transitioning to it. We have documents with status along the lines of editors/unofficial drafts, living documents, notes, and lowercase technical reports - was never intended to be conflated with W3C Technical Reports, not hosted w3.org, not using W3C logo, not implying W3C endorsed, among other things to say the least.
@ianbjacobs :
- To (better) ensure persistence and immutability, can the CG publish CG-FINALs under w3.org? Would you recommend that we do?
- Are CG-DRAFTs intended to be mutable or immutable snapshots? As I understand it, there can be multiple CG-DRAFTs with different versions of a report.
- As mentioned, majority of the documents listed under our Work Items are drafts of sorts. So, related to the above question, should we consider all of the documents as potentially equivalent to CG-DRAFTs or should we only publicise what may be deemed to be mature / advanced enough to be CG-DRAFT (and later CG-FINALs)? For instance, in loose terms, the documents that are versioned TRs (published at
https://solidproject.org/TR/{YYYY}/{shortname-YYYMMDD}) would qualify for CG-DRAFT, but I'm not sure how to approach the others in a fair way that both reflects their maturity as well as group's consensus.
Related:
- https://github.com/w3c/tr-pages/issues/102 - as discussed in the issue, this is rather important to distinguish ongoing WIP / drafts (along the lines of ED/UD) from CG-DRAFT publications.
- https://github.com/solid/specification/issues/373
- ...
@VirginiaBalseiro, @michielbdejong and I were chatting about CGs in the context of another group.
@csarven, @VirginiaBalseiro, and @michielbdejong,
If these documents are not (yet) CG Reports, please do not indicate that they were published by the Solid Community Group. Instead, please indicate which individuals drafted them. Because these documents are not CG deliverables, please remove mention of the CLA. (Indeed, you refer to the MIT license in the documents that I looked at.)
In other words: these are either CG Reports published by the group under the CLA and consistent with the requirements for CG Reports, or they are some other kind of document that has no relationship to any W3C process or group.
Regarding your questions above:
- All Final Reports must be published on w3.org (per the CG process). The recommended way to do that is via the cg-reports repo.
- CG drafts can be living documents; they do not need to be immutable (but can be).
CG drafts can be living documents; they do not need to be immutable (but can be).
Most Solid drafts had versioned snapshots published as "WD" and living documents available as "ED". Many documents use Bikeshed, which seems only to have two options—CG-DRAFT and CG-FINAL. I understand that no templates equivalent to ED and WD are available for Community Groups. Until finalized, should they use the CG-DRAFT template? We should still be able to have immutable releases similar to "WD" tagged with 0.x version numbers.
Linking from the 0.x tagged immutable version (~WD) to the latest version on the main branch (~ED) might be slightly nuanced since the link would commonly be labeled Editor's Draft. Is there a recommended term that could be used in CG drafts to label that link?
I am still getting up to speed on the status and plans for these documents. But if a document is not yet a Draft (or Final) CG Report, it should not claim to be the product of the CG (and not use the CG styles, license, etc.). If a call would be useful, let's find time next week.
If a call would be useful, let's find time next week.
That would be very useful, thank you! A number of us will be attending Solid Symposium next week and thus unavailable, but would you be able to join our weekly CG call on Wednesday May 8th at 14:00 UTC?
Quick status update:
I have the CG-DRAFT ready but decided not to PR yet. Traveling today. I will do it this week in a calmer moment/space. More details will be in the PR that we can review. A quick FYI for now:
- CG-DRAFT conforms to CG Report Requirements (but of course to be confirmed by W3C Team Community Process folks).
- It also conforms to / be compatible with some of the W3C publication rules (without interfering with CG Report Requirements), so it should be even workable (First Public) Working Draft or later states as needed. I've already went through this publication process with specs in WGs.
- CG-DRAFT can be published at https://solidproject.org/TR/protocol , with a link to "This version" for the specific snapshot (i.e., Version 0.11.0. e.g.,
https://solidproject.org/TR/2024/{YYYYMMDD}-protocol). - Once we get passed that publication, we can look into releasing CG-FINAL. I'd still like to encourage the Group to communicate with implementation experience, e.g., who is implementing or does not want to implement N3 Patch, ditto IRIs,..., which can be used to make another CG-DRAFT and/or towards the CG-FINAL.
- As for the Editor's Draft at https://solidproject.org/ED/protocol , that's also being updated to better clarify (e.g., in copyright, Status of this Document) that it is not a CG report and of course continue to not imply that W3C is endorsing it. The document will live on as is, and we can cut CG-DRAFT/FINAL(s) from it.
- Lastly, I will PR with some of the other documents listed under https://solidproject.org/TR/ along these lines.
Hi Virginia,
I am not having luck joining the call here; https://www.w3.org/events/meetings/a810b828-7a85-47b8-8a6d-2359a491a7f7/20240508T140000/
Ian
On Apr 26, 2024, at 10:21 AM, Virginia Balseiro @.***> wrote:
If a call would be useful, let's find time next week. That would be very useful, thank you! A number of us will be attending Solid Symposium next week and thus unavailable, but would you be able to join our weekly CG call on Wednesday May 8th at 14:00 UTC? — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you were mentioned.Message ID: @.***>
-- Ian Jacobs @.***> https://www.w3.org/People/Jacobs/ Tel: +1 917 450 8783
As for the Editor's Draft at https://solidproject.org/ED/protocol , that's also being updated to better clarify (e.g., in copyright, Status of this Document) that it is not a CG report and of course continue to not imply that W3C is endorsing it. The document will live on as is, and we can cut CG-DRAFT/FINAL(s) from it.
What reason do you see for the 'ED' not to be a CG draft? I'm looking at
- https://w3c.github.io/rdf-star/cg-spec/editors_draft.html
- https://w3c.github.io/rdf-star/cg-spec
and they both seem to use the 'CG-DRAFT` template; I also notice the Latest published version and Latest editor's draft terminology. I also noticed that the 'ED' has UNOFFICIAL watermarks.
Thanks again for including me in today's meeting. Here's a quick summary of my thoughts:
- In my opinion, a good outcome is for each specification to clearly communicate both its "W3C status" and its "Solid community status." I think we can find a way to do so, with the "W3C status" being the primary set of signals, and the "Solid community status" living within that.
- For the W3C status, all specifications in the group should start as Draft Reports with the corresponding styles, copyright statement, and status information.
- Some of these specifications may be taken up later by a Working Group. I suggest we discuss separately the value of asking contributors to make "full specification commitments" for those specifications. (The value will depend on a few factors including continuity of participation between the CG and WG.)
- For the Solid community status, during the call we started to discuss what signals the group wants to send to the community. We did not finish that discussion today, but I have a couple of observations:
- In my view, the "Editor's Draft" label does not communicate clearly what readers/implementers should expect.
- Please avoid terms like "Working Draft" or "Candidate Specification" that may create confusion with W3C WG signals.
- I thought I was hearing that stability signals might be useful (like "Core" and "Experimental") but I might be mistaken.
I am happy to continue to contribute to this discussion. Thanks!
What reason do you see for the 'ED' not to be a CG draft?
That might be begging the question =)
The initial intention was to not have our ED/protocol imply anything W3C labelled/endorsed, unless it has to do with CG-DRAFT. Right now ED/protocol uses the W3C ED stylesheet and the SotD is a bit mangled. It either needs to completely drop off association with W3C or as you seem to be asking about:
Our ED/protocol should only be unofficial CG-DRAFT. That'd be same as https://w3c.github.io/rdf-star/cg-spec/editors_draft.html AFAICT.
As I see it, if "unofficial" CG-DRAFT serves as a draft for us along the lines of what we've intended at ED/protocol (editor's draft), that'd be fine. When we want to make it "official", we propose CG-DRAFT (without unofficial watermark once W3C approves) updating our TR/protocol (and "this version" referring to https://solidproject.org/TR/2024/{YYYYMMDD}-protocol, which is similar to https://w3c.github.io/rdf-star/cg-spec redirecting to latest CG-DRAFT at https://w3c.github.io/rdf-star/cg-spec/2021-12-17.html ).
As mentioned earlier, CG-DRAFT doesn't have to be at TR/protocol (and could be under w3.org). However, CG-FINAL will be published under w3.org (e.g., https://www.w3.org/2021/12/rdf-star.html ) if need be.
Aside (speaking only based on my own understanding/observation):
As it currently stands at W3C, there is no ED or UD for CGs. While some CGs use(d) ED/UD - possibly because of process and tooling confusion, as well as nothing particularly prohibiting their use - they are incorrect and need to change. As Ian also mentioned above, CGs are only expected use CG-DRAFT/FINAL and to not communicate other kinds of document types/statuses found at W3C (see also https://www.w3.org/standards/types/#x1-summary ) or imply association with W3C.
So, I'd much prefer to have ED/protocol be an unofficial CG draft and remain that way rather than something else.
The W3C tr-pages issue that I've mentioned earlier highlighted that unnecessary ED/UD constraint at W3C (as I see it, IANAL) but that's not something for debate here. It is an open issue there, for W3C to consider acknowledging ED/UD for CGs because it is something used out there, and CGs can still publish CG-DRAFT/FINAL. But at this point, I don't care if unofficial CG-DRAFT essentially serves a similar purpose pragmatically speaking.
I don't think that UNOFFICIAL CG-DRAFT is defined somewhere. I just saw that some drafts have a UNOFFICIAL watermark used in their templates. Since many Solid drafts use bikeshed I would like to have clarity on which of the available templates should be used
I think all drafts should use CG-DRAFT, which seems to add the UNOFFICIAL DRAFT watermark, as seen here: https://solid.github.io/data-interoperability-panel/specification/
There is also UD, but it doesn't seem to be intended for CGs, as seen here: https://solid.github.io/data-interoperability-panel/primer/application.html
Does anyone see a problem with using the CG-DRAFT template for all CG work items, whether it is the latest published version (tagged/timestamped release snapshot) or the latest editor's draft (auto-generated from the main branch)? For me, this is the priority to answer because we still have time to figure out if and when to promote selected drafts to CG-FINAL.
For the Solid community status, we discussed what signals the group wants to send to the community during the call.
As I understand the maturity levels working groups use, reaching CR signals that the draft is primarily stable and ready for implementation. Many people find it problematic to go that far without actual implementation experience. Solid takes a more agile approach and strives for continued implementation feedback; there is already an advanced test suite for various product classes. Having versioned releases allows better communication with developers and clarity on which draft and version are being implemented.
For example https://communitysolidserver.github.io/CommunitySolidServer/latest/usage/notifications/ references a tagged 0.2 release of Solid Notifications Protocol.
Another example where we initially failed to do that is https://solidproject.org/TR/oidc We had yet to tag a release before it was implemented, as we needed to make a significant change and tagged it 0.1 after that change. This made communicating conformance much more challenging for implementations which so far only implemented the pre-0.1 version.
I would like to have clarity on which of the available templates should be used
W3C Team / Ian can correct me but as per https://www.w3.org/standards/types/#x2-1-w3c-community-group-report-or-w3c-business-group-report and https://www.w3.org/community/reports/reqs/ and irrespective to the tooling or environment that's used to create the report, the report needs to apply the CG-DRAFT template, styles, and include certain content (e.g., copyright, SotD).
The W3C stylesheet for CG-DRAFT by default applies the unofficial watermark, and the unofficial watermark is removed when the no-watermark word is a value of <body class> - I presume once approved by W3C Team.
https://solid.github.io/httpsig/ is already unofficial CG-DRAFT (using Respec).
I suggest all applicable Solid CG work items should first transition to (unofficial) CG-DRAFT. Any work item that is deemed to be mature to be "official", we (CG) can make a request to W3C Team Process - something we currently have in the pipeline for some specs any way.
Solid CG's use of versioning is already compatible with CG Report Requirements in the Copyright line: "REPORT NAME/VERSION". That is, the reports will say CG-DRAFT/FINAL as well as can mention the specific version. This helps to distinguish different CG-DRAFTs before a CG-FINAL.
The W3C stylesheet for CG-DRAFT by default applies the unofficial watermark, and the unofficial watermark is removed when the
no-watermarkword is a value of<body class>- I presume once approved by W3C Team.
@ianbjacobs During the meeting, I understood that CG chairs can use the CG system to request CG-FINAL status. At the same time, I'm unclear about how this process of W3C Team approving a regular CG-DRAFT works. I was under the impression that CG can publish any CG-DRAFT without an approval step, it only needs to follow https://www.w3.org/community/reports/reqs/
@elf-pavlik, the Team does not play any role in a group's decision to publish. I am joining this conversation to help with the requirements.
Since both ReSpec and Bikeshed add that UNOFFICIAL watermark, I assume this is required for any CG-DRAFT. I understand it is possible to override it and remove that watermark, but when is it appropriate to do it?
Looking again at
- https://w3c.github.io/rdf-star/cg-spec/editors_draft.html
- https://w3c.github.io/rdf-star/cg-spec
The Latest editor's draft does have the UNOFFICIAL watermark, while the Latest published version does not have any watermarks.
@ianbjacobs, is there official guidance on how the UNOFFICIAL watermark is expected to be used on a CG-DRAFT document?
The "W3C stylesheet for CG-DRAFT" being https://www.w3.org/StyleSheets/TR/2021/cg-draft
If the watermark is required, disabling it isn't a valid option. Does it mean that, for example, https://w3c.github.io/rdf-star/cg-spec doesn't meet the CG-DRAFT publishing requirements due to a lack of the UNOFFICIAL watermark?
@elf-pavlik, that appears to be a Final Report and so the expectations may be slightly different.
elfPavlik, AFAICT, i.e., don't quote me, both watermark and no-watermark is available from the CG-DRAFT stylesheet, so it is indeed there by design. What I'm concluding from that is that the no-watermark is applied when CG is done/ready/okay to publish the CG-DRAFT.
This is part of the clarifications that I'm seeking in https://github.com/w3c/tr-pages/issues/102 as part of the W3C documentation.
Ian, AFAICT, that is the CG-DRAFT. CG-FINAL is at https://www.w3.org/2021/12/rdf-star.html (and that also has the no-watermark word in body class.)