FDP 0 — How to write an FDP | proposal

[adrybakov]

This document formalises the procedure for creation of the design principles (FDPs) and add a template for an FDP.

In the rendered form it can be read at FDP-0 and FDP-template. The source code is available in the repository.

[adrybakov]

I suggest to leave this discussion open until beginning of January, as some of us will be taking Christmas/New Year break and will not be following the progress made during that time.

If then there will not be any unresolved objections, I will initiate acceptance of this FDP in the first half of January.

Consecutively, I suggest not to formulate any FDPs until this one is accepted.

[adrybakov]

Dear All,

With this message I would like to initiate the acceptance of the FDP 0 (Format Design Principle), that will govern the process of decision-making for the format's design if accepted.

Please read the proposed FDP here: spinham.github.io/spinham-format/fdp/fdp-0.html

IMPORTANT: If no objections to the FDP-0 will be raised, then it will be accepted in 12 days (on 20th of January, UTC+01:00).

Acceptance of the FDP's is one of the pivotal points in the format design, when every participant is notified explicitly. The first one is special as it governs itself, please use this issue for the discussion of this decision-making model as well, in addition to the discussion of the FDP-0's details. If you have questions about the process that are left unanswered by the FDP-0, please list them here as well, so the FDP-0 can be improved.

P. S. This model of decision-making is inspired by NumPy's NEPs.

@spinham/notifications-fdp

[lucas-wilkins]

Maybe I didn't read things well enough, but how do we indicate acceptance of this, how is "consensus" determined (importantly, where we express agreement/disagreement). I guess in future, this will be done via PRs, but where on them? If someone doesn't initially agree to something, then disappears, does this prevent consensus. Maybe this will all be obvious when things get rolling.

[adrybakov]

In my understanding this a framework of the process, so it does not attempt to be a rigid policy that defines all details of the procedure.

The important thing is that every member is aware of

• The proposal of the new FDP, so the discussion can be held about it
• The call for its acceptance, so FDP's final version can be reviewed again

The importance of "The Manager's" role for each FDP is to try to facilitate the consensus (for example, if there are two clashing opinions, advocate the compromise; if there is an inactive person, who made unresolved comments before, then try to reach to them, etc.).

The explicit notion of acceptance of each FDP by each member of the community is not expected. If a person has questions, concerns or objections that are important enough, then those can be raised during the discussion of the issue even before an FDP is formulated, then during the discussion of the formal document and finally during the specified period after the call for the final acceptance. If the person have no objections or does not follow the the project anymore at all, then they can stay silent. In that way the work on the project is organised and promote participation as the main mechanism of influence on the result. Therefore, increasing the chances for its progression.

The importance of advocating the pre-discussion in a topical issue before creating an FDP stems from the fact that all FDP's are recorded in history. Therefore, if the discussion will start from the formal document, then chances are that there will be an unreasonable number of Rejected/Withdrawn/Deferred FDP's to keep the track of. By allowing the pre-FDP discussion, the contour of the consensus can be drawn (the need for an FDP by itself can be tested as well) and then the discussion of the FDP will become more document-oriented and perhaps simpler.

Finally, the reason for opening a dedicated issue for each FDP and not discussing it within the PR. The amount of PRs for each FDP is arbitrary, as they can be used for the initial draft, changes, improvements, etc. The PRs are expected to be merged quickly, so everyone can read an FDP in the rendered form.

You are right that the things will become clear as we progress, perhaps some part of this FDP will be updated and improved with time. In particular, when the format will be close to be done (i. e. end of the implementation stage, beginning of the adoption stage), then the steering committee will be formed and that will probably be reflected in the FDP.

One of the important things to do right in such settings are the notifications of the FDP's creation and FDP's call for acceptance. At the moment (due to the historical reasons), the easiest guaranteed way to notify everyone who participate in the effort is by sending an e-mail from my address:

• It reaches everyone (the ones who joined the GItHub organisation and the few who did not do so yet.
• Not every issue is important for everyone, so some of the topics can be missed by people (i.e. not everyone is subscribed for every notification from GitHub).

That should change as well. One of the alternative ways, that I am testing now, is to use functionality of "Team" within GitHub's organisation to manage notifications:

• The mention of @spinham/notifications-fdp team supposed to send a notification email to everyone in that team (so every member of the organisation as of now). This mention should not be abused and used only for FDP-related notifications.
• Perhaps the code-specific teams can be created (i. e. @spinham/), so all developers of each tool can be summoned when required across issues.
• The subscription to the notifications of the team's mentions can be managed by each user individually, so the everyone can choose which one to receive and which one not to receive.

P. S. Did an e-mail caused by the mention of the "spinham/notifications-fdp" team arrived to you?

[adrybakov]

@lucas-wilkins, now let me address your concerns in a more practical way

Do you think that the FDP-0 should be rolled back and changed? It was created on 5th of December and since then no comments were left in this issue, so I assumed that there were no objections to it, therefore I moved for its acceptance. In this scenario the call for acceptance by 20th of January can be called of, discussion about the document can continue and the new call for the acceptance can be made when we agree on the document.

Or do you think that the document can be accepted within the called time (i. e. at 20th of January)? In such case, do you find you concerns to be answered and do you agree with the proposed document?

The third option is in the middle of the two above: perhaps you would like to propose some clarification of the writing, without changing the principles of the document, so it can still be accepted at 20th of January, but the text can be made more clear as well?

[adrybakov]

Personally, I think that it is a bad idea to try to make it perfect now, as we need to see which practices will work best for us.

I think that the updates to the FDP-0 will be made by extending it and not by replacing it with the new one (as the procedure describe in FDP-0 suggests). Of course, then some principles of the FDP-0 can be violated, especially in the more technical details (process of notifying, for instance). FDP-0 is a snake that eats itself in any case. In my opinion as long as everyone has a chance to object and as long as the procedural changes are not made silently, then we will be fine.

On the other side we should not go extreme and require a full procedure to be followed to fix a typo or a grammar mistake. As the document history is recorder in the git repository, then everything can be recovered. And in line with the FDP-0's spirit, the trajectory of the development and "enforcement" of the principles listed in any FDP will be guaranteed by the participation: if the person care about the outcome of the projects, then each of us has all the tools to affect it and question decisions made by others. On the other side, we are not bound by having to get explicit approval of every PR by each member (>30), which can become tedious very fast.

EDIT: fix some typos

[adrybakov]

As unresolved issues remained open, the acceptance of this FDP is postponed.

@spinham/notifications-fdp

[adrybakov]

@lucas-wilkins, could you reflect on the questions posted above, please?