Document Status
- Modified
- 2024-01-10
- Reason
- This document is no longer in effect and is no longer being updated here. For the latest information on the W3C Solid Community Group, please refer to its repository, charter, and contributing guidelines.
Thank you for investing your time in contribution to the Solid project!
This repository contains the source code of the work on Solid Technical Reports (TR) of the W3C Solid Community Group (CG) to meet the needs of the Solid Project.
The TRs include specifications, use cases and requirements, best practices and guidelines, primers and notes about the Solid ecosystem.
Read the Solid Code of Conduct and the Positive Work Environment at W3C: Code of Ethics and Professional Conduct to keep our community approachable and respectable.
See additional resources for education and training to promote a positive work environment.
The key words “MUST” and “MUST NOT” are to be interpreted as described in BCP 14 RFC2119 RFC8174 when, and only when, they appear in all capitals, as shown here.
In order to be a substantive contributor to work items, you MUST be a member of the CG. It’s easy to join the CG if you’d like to contribute. People agree to the W3C Community License Agreement (CLA) upon joining the CG.
The works in this repository use the MIT license.
We accept different types of contributions as described below.
To ensure that anyone can follow along a contribution and support verification, provide citations to significant units of information, e.g., references to specific requirements in technical reports, decisions made in a formal meeting. To promote accountable discourse, request citations when questioning uncited claims.
If you'd like help troubleshooting a pull request (PR) you're working on, have a great new idea, or want to share implementation feedback, join us in Solid specification chat.
Issues are used to track tasks that contributors can help with. If an issue has a triage label, we haven't reviewed it yet and so you are not encouraged to begin work on it.
If you've found something in the content or the website that might need to be updated, search open issues to see if someone else has reported the same thing. If it's something new, open an issue. We'll use the issue to have a conversation about the problem you want to fix.
A pull request is a way to suggest changes in our repository.
We aim to have our documents internationalized and available in multiple languages. The source content in this repository is written in English. We accept contributions to localize the English content.
Each CG work item listed at Solid Technical Reports has its own repository. It is strongly encouraged that any issues and PRs are made at their source.
The persistent version of technical reports published in this repository (see publishing technical reports are intended to be read-only snapshots of the CG work items.
Solid Panels focus on certain work streams, with an aim to propose technical reports for the Solid ecosystem.
A low-barrier way to add concrete suggestions is to submit a user story. User stories are descriptions of desired features written in a special way, see the description there for details. User stories might then be used when formulating use cases and requirements.
If you spot a problem with the technical reports being worked on in this repository or would like to request a feature, search if an issue already exists. If a related issue doesn't exist, you can open a new issue. In the issue, include relevant information that can help others, e.g., links to specifications, issues, implementations, test suite, discussions.
Scan through our existing
issues to find one that
interests you. You can narrow down the search using labels as filters. See
Labels
for more information. If you find an issue to work on, you are welcome to open
a PR with a fix.
- Install Git
- Fork the repository.
- Create a working branch and start with your changes!
Commit the changes once you are happy with them. See Atom's contributing guide to know how to use emoji for commit messages.
Once your changes are ready, don't forget to self-review to speed up the review process:zap:.
You are strongly encouraged to review your own PR first.
For content changes, make sure that you:
- Confirm that the changes meet the user experience and goals outlined in the content design plan (if there is one).
- Compare your PR's source changes to staging to confirm that the output matches the source and that everything is rendering as expected. The W3C service to creating diff between HTML pages can also be used.
- Review the content for technical accuracy.
- Review the content using the translation guide for writers and the W3C Manual of Style as guides.
- Review the content to use inclusive language. Celebrate people/names from under represented ethnic/cultural backgrounds in examples, e.g., unique forenames in Earth, example person names.
- If there are any failing checks in your PR, troubleshoot them until they're all passing.
- Follow the Publication Rules
When you're finished with the changes to documents that are maintained in this repository, create a PR.
- Include atomic commits, small PRs: "one concern, one PR".
- In the PR comment, provide as much context and evidence to help reviewers evaluate the PR. Identify, classify, describes the changes as per W3C Process Correction Classes.
- Don't forget to link PR to issue if you are solving one.
- We can ask for changes to be made before a PR can be merged, either using suggested changes or PR comments. You can apply suggested changes directly through the UI. You can make any other changes in your fork, then commit them to your branch.
- As you update your PR and apply changes, mark each conversation as resolved.
- If you run into any merge issues, checkout this git tutorial to help you resolve merge conflicts and other issues.
- You can attribute a commit to more than one author by adding one or more
Co-authored-by: NAME <NAME@EXAMPLE.COM>per line to commit's message (after two empty lines). See github tutorial.
Congratulations 🎉 Solid community thanks you ✨.
In general, all documents in scope of the group are welcome. Work items can be documents or software.
- Propose new work item as an issue in https://github.com/solid/specification and propose it as an agenda topic in a group meeting.
- Include publicly accessible link to abstract or draft.
- List and link to owners (at least 1 person for advancing the work item and 1 other person).
- Answer the following questions in order to document how you are meeting the
requirements for a new work item at the W3C Solid Community Group. Please
note if this work item supports certain programs or another government or
private sector project.
- Explain what you are trying to do, using no jargon or acronyms.
- How is it done today, and what are the limits of the current practice?
- What is new in your approach, and why do you think it will be successful?
- How are you involving participants from multiple skill sets and global locations in this work item? (Skill sets: technical, design, product, marketing, anthropological, and UX. Global locations: Africa, the Americas, APAC, Europe, Middle East, Antarctica.)
- What actions are you taking to make this work item accessible to a non-technical audience?
This section describes how to prepare the technical reports and how they'll be published on the Solid website.
- Content: the full content of the technical report MUST be human-readable with HTML alone. It is strongly discouraged that any CSS and JavaScript interferes with the accessibility of the content.
- Offline-friendly: there MUST not be any mandatory external dependencies (e.g., a network connection) to retrieve, to render, or to manipulate the content of the article.
- Privacy: scripts MUST not be used to identify or track readers.
There are two parts to publishing a technical report that applies to all reports:
- PR including the technical report in HTML and all local script and media files.
- Updating the technical report index (if necessary).
Published documents will be publicly accessible under the paths
https://solidproject.org/TR/ or https://solidproject.org/ED/.
The PR for a versioned technical report MUST include two HTML documents:
- "Latest version" of the TR under the root (
/) directory. - "This version" (also known as the persistent version) of the TR under
the
/{YYYY}/(year in 4 digits) directory.
We recommend that the latest version of the technical reports use a
{shortname}, e.g., protocol, wac, and the persistent version of the
technical report follows the following form: {shortname}-{YYYYMMDD}.
All files use common file name extensions, e.g., .html.
The documents will be published under the path https://solidproject.org/TR/.
For example, the Solid Protocol is available from the following URLs:
- This version: https://solidproject.org/TR/2022/protocol-20221231
- Latest version: https://solidproject.org/TR/protocol
When a new version of the technical report is made available, we follow the same process. The updated "latest version" document will then link to the new latest persistent version. All persistent versions link to the latest version.
Versioned technical reports MUST indicate their version using the Semantic
Versioning scheme in the document. The first release
of a technical report MUST use 1.0.0 (for version-core). Any release can
use a pre-release value part of the version indicating the document status
and the publication date, e.g., "Version 1.0.0-CG-DRAFT" indicates a CG Draft.
The PR for a non-versioned technical report MUST include one HTML document and follow the same requirements as in "latest version" (see versioned technical report).
The documents will be published under the path https://solidproject.org/TR/.
The PR for a non-versioned technical report MUST include one HTML document and follow the same requirements as in "latest version" (see versioned technical report).
The document will be published under the path https://solidproject.org/ED/.
For example, the Editor's Draft of the Solid Protocol is available from
https://solidproject.org/ED/protocol .
When a new technical report is added, information about it is modified, or a new work item is being worked on by the CG, a follow-up can PR can be made to update the Technical Report index.
W3C CG reports are not required to follow the publication requirements as W3C reports on the standards track. However, we recommend using the W3C's Publication rules for Recommendation (“REC”) as a guideline. Solid CG's technical reports differ along the lines of document status, rights, identifiers. To help readers already familiar with W3C technical reports, it is recommended to maintain the same look and feel.
See also the W3C Manual of Style guide containing best current practice, written for editors and authors of W3C technical reports.
We also make the following recommendations:
- MUST be a valid HTML5 document (see also the W3C Markup Validation Service).
- MUST include published and modified dates (
YYYY-MM-DD). - MUST use the MIT License (with URL: http://purl.org/NET/rdflicense/MIT1.0 ).
- Follow the Internationalization Best Practices for Spec Developers.
- Follow the Linked Data design principles. Give all significant units of information, e.g., concepts, requirements, an identifier, and provide a description using a concrete RDF syntax (see also Spec Terms).
- Cite the source resource in which consensus was reached for a given statement.
- Changelog from previous published releases (if applicable).
- Considerations section, e.g., Self-Review Questionnaire: Security and Privacy, Accessibility, Internationalization, Societal Impact.
- Conformance Classes section to identify who and/or what will implement the specification.
- Document wilful violations.
- Use consistent spelling throughout the document.
Also see https://www.w3.org/Consortium/Process/#decisions for general guidance.
Unless there is a prior CG decision otherwise, changes to TRs use the W3C Process Correction Classes as follows:
| Correction Class | Requirements | Time |
|---|---|---|
| No changes to text content | Editors MAY PR and/or merge at their discretion. | Within 5 days or 2 meetings. |
| Changes that do not functionally affect interpretation of the document | Editors SHOULD PR and/or merge at their discretion. | Within 5 days or 2 meetings. |
| Other changes that do not add new features | MUST PR. | Within 10 days or 2 meetings. |
| New features | MUST PR. | Within 10 days or 2 meetings. |
| Changes to the contents of a registry table | Editors or chairs MUST PR. | Within 10 days or 2 meetings. |
TRs might refer to or make use of namespaces for specific functionality. The CG handles the management of Solid vocabularies under its responsibility through the solid/vocab repository.
The policy for the management of Solid vocabularies under the W3C namespace is described in Adding to W3C RDF Namespaces.
The CG Meeting Guidelines describes how to participate and record meetings. There is a minutes template that can be used by scribes to transcribe the meeting.
The opinions of CG members may carry particular weight, whether they are expressed within our community or elsewhere. As a CG member:
- It is assumed you are speaking as an individual unless you state otherwise.
- If you want to express the opinion of your organisation or a group you are affiliated with, make it clear before you state their view.
- Do not use phrases like "on behalf of the CG" or "the CG thinks that" unless the group has asked you to do so.
- When communicating CG decisions, provide references to what was decided and what was not decided.