Update decision-making-processes.md

[Mitzi-Laszlo]

Had a shot at incorporating feedback from @shaunagm on https://github.com/solid/information/issues/132

Please feel free to add and edit further.

The proposal is to generate the first draft of the Solid specification v0.8 in the following way, as described in the Solid Specification v0.8 Solid Project . After Solid spec v0.8 the following decision making process could be used to make changes to the Solid spec.

[Mitzi-Laszlo]

This draft process is being tested on the following pull request https://github.com/solid/solid-spec/pull/92

[Mitzi-Laszlo]

@konobi suggested using the tool https://www.loomio.org, any thoughts on this?

[shaunagm]

I really like Loomio in theory but have never used their tools and don't know many (any?) people who have. My understanding is that it's better for small groups, but if you want hundreds or more people able to participate in the decision-making process, it quickly gets too expensive. So it might be a good tool if you have an elected/appointed board/panel making decisions in a democratic and transparent way, but not a good tool if you want mass participation.

[elf-pavlik]

Thanks @Mitzi-Laszlo !

To combine information from the solid-spec, web-access-control-spec, and the webid-oidc-spec into the specification repository using the W3C specification template to create Solid specification v1.

I think web-access-control-spec and webid-oidc-spec could stay independent specs and solid spec could just depend on them.

This project will be carried out in a public repository. Pull requests and issues are welcome although there is no commitment from the project team to respond during the project. If there is a difference of opinion between the Project Team members, the Project Manager will decide the route forward.

That sounds to me more like Project Team members acting as authors and @RubenVerborgh (Project Manager) acting as editor. Commonly specs have more authors and just few editors.

@konobi suggested using the tool https://www.loomio.org, any thoughts on this?

IMO we shouldn't try to add another communication tool unless we really start feeling pain from github lacking some features.

I will stay offline for a week, I hope I'll get back online on time for next community call on 23rd :bowing_man:

[RubenVerborgh]

I think web-access-control-spec and webid-oidc-spec could stay independent specs and solid spec could just depend on them.

Agreed. WebID-OIDC can be used independently of the pod spec. (@michielbdejong Probably another indication why "the" Solid spec will not be sufficiently precise; OIDC is not necessarily a subspec, but an independent spec that can also be used to front other HTTP interfaces such as TPF.)

My practical suggestion would be to keep al spec documents in one single repository https://github.com/solid/specification/, but they can (should?) have different editors. (For instance, I am likely not the right editor for WebID-OIDC.)

[Mitzi-Laszlo]

Another helpful reference is https://tc39.github.io/process-document/

[RubenVerborgh]

I would like to have a separate document/process for spec editing.

I do not consider spec editing a decision process; it is writing down what people have agreed upon. (Spec making is a process.) As such, I don't think it fits in a "decision making process" document.

So in my mind, there is a separate document "spec writing process", and in my ideal world, it says something like:

• editors write down in a very precise way what people have agreed on
• the level of detail might reveal additional discussion
• every addition to the spec is available as a PR for at least 7 days and requires 2 reviews
• in case an addition to the spec becomes the topic of discussion/disagreement, then that topic has to move to a decision making process

[Mitzi-Laszlo]

Yes, agreed, Solid specification writing is crucial to Solid and deserves special attention. However, I do see decisions needing to be made in that writing process.

How do people come to an agreement about what to write? Who are 'people'?

[Mitzi-Laszlo]

@pmcb55 thanks for eagle eye typo work, have updated the pull request to include the fix

[shaunagm]

@RubenVerborgh - it sounds like you think specification editing will require very little discretion and cause very little controversy. But as you say, there may be edge cases where we'd want to use a decision-making process. I think the key thing to figure out is how that decision-making process would be triggered. What would the process be, and who would be able to trigger it? It may never get triggered, but it's good to have a plan just in case.

[RubenVerborgh]

How do people come to an agreement about what to write?

We start from the spec 0.7 document and NSS.

Who are 'people'?

Anyone in the community as far as I'm concerned.

But I don't think it's going to be that difficult at first; perhaps the process can be adjusted once it does.

[RubenVerborgh]

@RubenVerborgh - it sounds like you think specification editing will require very little discretion and cause very little controversy.

Indeed, perhaps just an example of what would be done.

Current draft document:

IMPORTANT: a default Content-Type: text/turtle will be used for requests for RDF resources or views (containers) that do not have an Accept header.

An editor could instead write in the spec:

When the client does not send an Accept header, the server MUST assume an Accept header of text/turtle.

Aside from the technical meaning, note how the second is a clearer and non-ambiguous version of the first (it's clear who does what etc.). This is non-controversial, we just properly write down something we've been doing for ages.

Now in the process of writing this down, because of the more exact language, new questions might arrive. For instance, MUST or SHOULD? (They are defined terms in spec language.)

Then we can discuss those things, and 90% of cases there will be agreement. So then we just accept the PR after a week. If people don't agree, we move it to an official decision process.

But as you say, there may be edge cases where we'd want to use a decision-making process. I think the key thing to figure out is how that decision-making process would be triggered. What would the process be, and who would be able to trigger it?

An editor sees that people don't agree (i.e., it's not just one person objecting, but there is a genuine concern), then it moves to decision. Something like that.

[Mitzi-Laszlo]

How about we have free writing via pull requests that are left open for 36 hours before being merged by the Solid Team.

If 5 people in the Solid Panel raise a concern by writing 'concern' in the pull request then the vote process is triggered.

The Solid Panel can have criteria to apply and are appointment by the Solid Leader. Then there could be a list of the names of the people on the Solid Panel.

That way we give the possibility for free uninterrupted writing of the Solid spec while also having a mechanism to raise concern so that the free writing result is something that everyone can get on board with.

[bblfish]

Perhaps one could be inspired by the Scala community process too. They host a repository of the best scala libraries, which I think they use when making improvements to the compiler to see what breaks. I am not sure how one would translated this to Solid though, as it is not just a matter of compiling apps and apps are a lot more difficult to test.

Google uses its crawl of the web to test new spec improvements and how that would affect the changes to the existing useful web pages.

Currently there are not so many deployed apps perhaps, but it would make a good case for having them listed, and so debates can point to code that may need changing if something is changed.

[RubenVerborgh]

How about we have free writing via pull requests that are left open for 36 hours before being merged by the Solid Team.

Too short I'd say. Not all people are online once every 24 hours.

[Mitzi-Laszlo]

Would a week be a good time period?

[RubenVerborgh]

A week sounds reasonable to me; perhaps could/should also be tied into the call schedule.

[Mitzi-Laszlo]

Quick update, Justin has added his thoughts on the following links:

https://github.com/solid/information/pull/167

https://github.com/solid/information/pull/166

https://github.com/solid/information/pull/165

[Mitzi-Laszlo]

See https://github.com/solid/culture for further conversation on this topic