This repository details how changes to Solid may be proposed and accepted.
The following is a description about how changes to the specifications in the Solid ecosystem may be proposed and accepted.
The current development on the Solid ecosystem is carried out in the Solid Specifications repository. The Unofficial Draft predating the current development is still available for historical reference.
All manner of contributions are important - whether identifying problems, asking questions, or proposing normative changes.
There are many topics, problems, or ideas best tackled by a group of people with a specific set of domain expertise. For these cases, we have Solid Panels.
Solid Panels are groups of individuals focused on a specific problem or domain relevant to Solid, with an aim to propose changes to the Solid Specification. Anyone may join a panel or suggest a new panel.
Domains may be technical, non-technical, or some combination of the two. For example, a Security Panel could focus on the evaluation and advancement of the Solid security model.
A list of Solid Panels is maintained at panels.md. This listing helps people find panels they may want to participate in, and helps editors find panels to consult as part of the editorial process.
Panels may request to have a repository created within the Solid Github Organization. These requests should be made by submitting an issue to solid/process. The request should include the proposed name of the repository, and how it will be used. Any editor may reject a proposed name and request an alternative. All panel members will receive Maintain Permissions on the panel repository, unless it is subject to editorial review, which would require that it employ a different permission structure. Panel repositories that are inactive for more than six months may be archived by Solid Administrators.
Stakeholders are those affected by normative changes to the Solid Specification. There are two types of Stakeholders; Solid Users and Solid Implementers. It is important to consider them both when proposing changes, and adhering to the W3C priority of constituencies is encouraged. A Stakeholder may be both a user and an implementer.
Stakeholders who have opted to identify themselves publicly are listed at stakeholders.md. Anyone may decide to identify themselves publicly as a Solid Stakeholder, but it is not mandatory. Identified stakeholders may be consulted for feedback as part of the editorial process.
Solid Users are individuals, companies, or organizations who access data stored in a Solid Pod.
Solid Implementers are companies or organizations who are implementing the Solid Specification. A Solid Implementer may be any combination of Identity Provider, Pod Provider, and Application Provider.
How to Make Changes
This section details how changes to the Solid Specification may be drafted, proposed, and accepted.
Anyone may submit a proposal to alter this process. These proposals will not be reviewed by the editors. They will be reviewed only by Tim Berners-Lee, who is the Solid Director.
Anyone may propose improvements to the Solid Specification. Here are some examples of different ways to contribute:
- Submit a pull request or issue on the Solid Specification repository in GitHub
- Make a suggestion to the Solid Authorization Panel chat room about a change you'd like to see in Web Access Control
- Make a suggestion on the Solid W3C Community Group mailing list to form a new Solid Panel, or join an existing Solid Panel
- Propose an item for the W3C Solid Community Group call
Proposals for substantive changes to the Solid Specification go through an editorial review process. A change is considered substantive when it alters the normative text of the Solid Specification or the Solid Roadmap. Any proposal must be realistic and reasonable to implement, preferably with example implementations, and demonstrable support from Implementers.
Any proposal should also be accompanied with a reasonable explanation of the need for the proposed change. For example:
- Adding a new capability that satisfies one or more new use cases, or to reflect a new capability already incorporated consistently into multiple implementations.
- Removing something because it was never adopted by Implementers for legitimate reasons, or because there has been a collective shift in focus away from that feature and it no longer makes sense to keep it.
- Changing something to a simpler design that is able to address the same use case(s) with less complexity, or a change that resolves one or more identified issues in real-world use.
A draft proposal often involves public discussion before being formally presented for review. After these discussions have occurred and a draft proposal has reached a sufficient level of maturity, it should be presented as a candidate proposal, asking Stakeholders and Panels if there are any major objections.
When there are objections, notify the Solid Panels and Stakeholders about the final proposal with an invitation to vote. If there are options, detail them along with the implications of the options. The final proposal needs to be open for one week to give others a chance to vote. To show your support for a proposal write +1. To show your disapproval for a proposal write -1 along with a detailed reason for the disapproval and a suggestion for a preferred alternative. To abstain type 0 when you have no opinion. If you do not vote by the end of the week it will be assumed that you abstain. At the end of the week anyone may publish an overview of the vote results per Solid Panel and Stakeholder.
Candidate proposals to the Solid Specification submitted for review go through an editorial process before they are accepted. Candidate Proposals to change the Solid Specification must be submitted for editorial review before they are accepted, along with the results of any votes taken.
To help broad consensus form, it is suggested that each proposal be brought to the attention of the Editors at some defined contact points during its life cycle. These contact points are:
- When a reason to change or extend the specification is first encountered, an issue is opened. The issue is then used for further communication with the Editors.
- Panels may create or adopt issues, and Panels should notify Editors that such discussion has started.
- When a Panel reaches rough consensus on an issue, the Panel should notify the Editors, indicating in informal text what the consensus entails and who participated in forming it.
- When a Panel starts drafting the text of a proposal, the Panel should notify the Editors.
The above is not required and may be superfluous for small changes, but it is likely to speed up the overall process for larger issues.
An Editor determines whether a Candidate Proposal includes a substantive change and marks it accordingly. If there is any disagreement among Editors, the Candidate Proposal will be automatically marked as including a substantive change.
Candidate Proposals with substantive changes require three Editors who are assigned to the material being modified to actively approve the proposal, with no Editors from the Editorial Team actively rejecting. If there are less than three Editors assigned to the material being modified, then other Editors from the Editorial Team may participate. Editors may abstain. Candidate Proposals with substantive changes must remain open for at least one week before final acceptance. If an Editor does not vote by the end of that week it will be assumed that they abstained, providing a good faith attempt has been made to involve those who may be likely to disagree. Once the Candidate Proposal has successfully passed editorial review and the specified wait-time has elapsed, it may be merged by an assigned Editor.
Candidate Proposals without substantive changes require one Editor assigned to the material being modified to actively approve the proposal, with no Editors from the Editorial Team actively rejecting, and may be merged immediately by an assigned Editor. An assigned Editor may approve and merge their own non-substantive changes. Anyone from the Editorial Team has the right to revert a non-substantive change, but are encouraged to communicate with the assigned Editor that merged it first. Any revert must be accompanied by a reasonable explanation. If the change is reverted because they believe it to be substantive, that must be included in the explanation.
Editor appointments and their respective assignments are made by the Solid Director. The Editorial Team is comprised of all the Editors appointed by the Solid Director, who are listed at editors.md, along with their assignments, contact details, and affiliations. Anyone may apply to be an Editor, and must include one or more requested editorial assignments as part of their application. These requests are not reviewed by other Editors. They are reviewed only by the Solid Director. Editor applications that can demonstrate the support of a relevant panel or group of community members will be favorably considered.
Repositories requiring editorial review are listed in editors.md. Each repository has one or more assigned editors, and only assigned editors are permitted to merge into the master branch of these repositories, per the proposal review process.
Editors have Admin Permissions on the repositories they are assigned to, and are permitted to grant Write Permissions to other contributing authors on the same. All members of the Editorial Team have Write Permissions on all repositories requiring editorial review listed in editors.md.
Administrators are granted privileged access to control the tools, systems, and services used for advancing the Solid. This includes the Solid GitHub organization, Solid Gitter channels, the Solid Forum, and the Solid Website.
Administrators belong to the Administrators Team in the Solid GitHub Organization and have Admin Permissions on all repositories therein. Administrators have Owner Permissions for the Solid GitHub Organization.
Becoming an Administrator
Administrators are appointed by the Solid Director. Administrators are listed at administrators.md along with their contact details and affiliations. Anyone may apply to be an Administrator. Administrator applications are not reviewed by other Administrators. They are reviewed only by the Solid Director.
The Creators are responsible for creating content for the solidproject.org website.
Creators are appointed by the Solid Director.
The solidproject.org website is linked to the
master branch of the GitHub repo solid/solidproject.org. Draft versions of updates of the website are worked on in the
staging branch of the same repo. The draft work is documented on the Creators project board.
Anyone can make suggestions by commenting or submitting pull requests to the
staging branch of solid/solidproject.org to be reviewed by Editors, and be approved by the Solid Director before they go to
Spelling, grammar, broken links, and other minor changes do not need to be approved by the Solid Director and can be updated or approved directly in
staging by the Creators. Changes larger than that, but that do not significantly alter the website content (such as referencing community activity outside of the website) also do not need to be approved by the Solid Director in order to be applied to
staging, as long as they have been approved by one of the Editors.
Creators can move changes in
master (and hence solidproject.org) at any time, since
staging will only contain approved changes.
Solid culture documentation was put together with inspiration and learnings from the following resources.
- W3C Good practice for running a group
- Python (2018) Python Language
- Elinor Ostrom (2005) Understanding Institutional Diversity.
- Chales M Schweik and Meelis Kitsting (2010) Applying Elinor Ostrom’s Rule Classification Framework to the Analysis of Open Source Software Commons. Transnational Corporations Review
- Sean McDonald (2019) Reclaiming Data Trusts. CIGO
- Aymeric Augustin Django