.. _fdp-0: *************************** FDP 0 — How to write an FDP *************************** =========== ====================================== =========== ====================================== **Author** Andrey Rybakov (rybakov.ad@icloud.com) **Created** 04.12.2025 **Status** Draft =========== ====================================== What is a FDP? ============== FDP - "Format's Design Principle" is a design document that describes a design principle for the spin Hamiltonian format. It is an UTF-8 coded text file written with the |reStructuredText|_ that follows the :ref:`fdp-template`. A plain text file can be proposed as well, in that case the Maintainer is responsible for converting it to the |reStructuredText|_. Workflow ======== It is recommended to discuss the idea of FDP in the topical issue before proposing the formal FDP document. Each FDP proposal should have a responsible person — the Manager — who will submit a PR and will be responsible for shepherding the discussion, addressing comments, and updating the document as needed. Proposal -------- When the author(s) feel that the FDP is ready for review, a PR should be submitted to the main brunch of the |spinham-format|_ via GitHub's pull request to the "docs/source/fdp" directory with the name "fdp-.rst". The PR should be labeled with the "[FDP]" label. At the same time an issue named "FDP - | proposal" should be created for the discussion of the FDP. All initial proposals should have the "Draft" status. At the earliest convenience the PR should be merged by a maintainer regardless of the state of the discussion. New PRs can be created by the Manager to update the FDP or by Maintainer to set it status, update format, etc. Discussion and review --------------------- Any member of the organization can leave comments, raise issues or propose changes within the topical issue. The Manager is responsible for addressing comments, updating the document as needed. The discussion should continue until a consensus is reached among the members. Acceptance ---------- When the consensus is reached, the Maintainer, at request of the Manager, should notify all members stating that the FDP is ready and will be merged unless objections are raised within 7 days. If no objections are raised within that period, then the FDP becomes ``Accepted``. Period of 7 days can be extended by the Manager, in that case the duration shall be communicated in the notification. Rejection --------- If at any moment the consensus is that the idea of the FDP is not a good one or the vote rejects the proposal if the discussion becomes stale, then FDP becomes ``Rejected``. In that case it is still recorded in the list of FDP's for future reference. Withdrawn --------- The Manager can decide to withdraw the FDP at any moment before it becomes ``Accepted`` or ``Rejected``. Withdrawn FDP's are recorded in the list of FDP's for future reference. Stale discussion ---------------- If the consensus can not be reached and the discussion becomes stale, then the decision about the FDP shall be made by the vote with the formula 1 tool = 1 vote. The vote is organized by a Maintainer and can be called by the Manager or Maintainer after the discussion becomes stale. Replaced -------- The FDP becomes ``Replaced`` if a new FDP, that supersedes it, is ``Accepted``. Header ====== Each FDP should start with a preamble, that shall include the following mandatory fields * Author: * Created: * Status: