CIP-0001, CIP-9999, README & templates: periodic update

.github/CIP-TEMPLATE.md

@@ -14,14 +14,15 @@ License: CC-BY-4.0
 
 <!-- Existing categories:
 
-- Meta     | For meta-CIPs which typically serves another category or group of categories.
-- Wallets  | For standardisation across wallets (hardware, full-node or light).
-- Tokens   | About tokens (fungible or non-fungible) and minting policies in general.
-- Metadata | For proposals around metadata (on-chain or off-chain).
-- Tools    | A broad category for ecosystem tools not falling into any other category.
-- Plutus   | Changes or additions to Plutus
-- Ledger   | For proposals regarding the Cardano ledger (including Reward Sharing Schemes)
-- Catalyst | For proposals affecting Project Catalyst / the Jörmungandr project
+- Meta      | For meta-CIPs which typically serves another category or group of categories.
+- Wallets   | For standardisation across wallets (hardware, full-node or light).
+- Tokens    | About tokens (fungible or non-fungible) and minting policies in general.
+- Metadata  | For proposals around metadata (on-chain or off-chain).
+- Tools     | A broad category for ecosystem tools not falling into any other category.
+- Plutus    | Changes or additions to Plutus
+- Ledger    | For proposals regarding the Cardano ledger (including Reward Sharing Schemes)
+- Consensus | For proposals affecting implementations of the Cardano Consensus layer and algorithms
+- Network   | Specifications and implementations of Cardano's network protocols and applications
 
 -->
 

.github/CPS-TEMPLATE.md

@@ -1,8 +1,8 @@
 ---
 CPS: ?
 Title: ?
-Status: Open
 Category: ?
+Status: Open
 Authors:
     - John Doe <[email protected]>
 Proposed Solutions: []
@@ -14,14 +14,15 @@ License: CC-BY-4.0
 
 <!-- Existing categories:
 
-- Meta     | For meta-CIPs which typically serves another category or group of categories.
-- Wallets  | For standardisation across wallets (hardware, full-node or light).
-- Tokens   | About tokens (fungible or non-fungible) and minting policies in general.
-- Metadata | For proposals around metadata (on-chain or off-chain).
-- Tools    | A broad category for ecosystem tools not falling into any other category.
-- Plutus   | Changes or additions to Plutus
-- Ledger   | For proposals regarding the Cardano ledger (including Reward Sharing Schemes)
-- Catalyst | For proposals affecting Project Catalyst / the Jörmungandr project
+- Meta      | For meta-CIPs which typically serves another category or group of categories.
+- Wallets   | For standardisation across wallets (hardware, full-node or light).
+- Tokens    | About tokens (fungible or non-fungible) and minting policies in general.
+- Metadata  | For proposals around metadata (on-chain or off-chain).
+- Tools     | A broad category for ecosystem tools not falling into any other category.
+- Plutus    | Changes or additions to Plutus
+- Ledger    | For proposals regarding the Cardano ledger (including Reward Sharing Schemes)
+- Consensus | For proposals affecting implementations of the Cardano Consensus layer and algorithms
+- Network   | Specifications and implementations of Cardano's network protocols and applications
 
 -->
 

CIP-0001/README.md

@@ -1,8 +1,8 @@
 ---
 CIP: 1
 Title: CIP Process
-Status: Active
 Category: Meta
+Status: Active
 Authors:
     - Frederic Johnson <[email protected]>
     - Sebastien Guillemot <[email protected]>
@@ -88,7 +88,8 @@ Path to Active                                  | Organised in two sub-sections
 _optional sections_                             | May appear in any order, or with custom titles, at author and editor discretion:<br/>**Versioning**: if [Versioning](#versioning) is not addressed in Specification<br/>**References**<br/>**Appendices**<br/>**Acknowledgements**
 Copyright                                       | The CIP must be explicitly licensed under acceptable copyright terms ([see below](#licensing)).
 
-> **Note** Each of these section titles (*Abstract* onward) should be an H2 heading (beginning with markdown `##`).  Subsections like _Versioning_ or _Acceptance Criteria_ should be H3 headings (e.g. `### Versioning`).  Don't include a H1 title heading (markdown `#`): for web friendly contexts, this will be generated from the Preamble.
+> [!NOTE]
+> Each of these section titles (*Abstract* onward) should be an H2 heading (beginning with markdown `##`).  Subsections like _Versioning_ or _Acceptance Criteria_ should be H3 headings (e.g. `### Versioning`).  Don't include a H1 title heading (markdown `#`): for web friendly contexts, this will be generated from the Preamble.
 
 ##### Header Preamble
 
@@ -97,9 +98,9 @@ Each CIP must begin with a YAML key:value style header preamble (also known as _
 Field          | Description
 ---            | ---
 `CIP`          | The CIP number (without leading 0), or "\?" before being assigned
-`Title`        | A succinct and descriptive title.  If necessary, use a `-` delimiter to begin with an applicable classification (see [Naming CIPs with similar subjects](#naming-cips-with-similar-subjects)).
+`Title`        | A succinct and descriptive title.  If necessary, use a `-` delimiter to begin with an applicable classification (see [Naming CIPs with similar subjects](#naming-cips-with-similar-subjects)).  Don't use backticks (<code>`</code>) in titles since they disrupt formatting in other contexts.
+`Category`     | One of the editorially accepted [categories](#categories) covering one area of the ecosystem.
 `Status`       | Proposed \| Active \| Inactive (.._reason_..)
-`Category`     | One of the registered [categories](#categories) covering one area of the ecosystem.
 `Authors`      | A list of authors' real names and email addresses (e.g. John Doe <[email protected]>)
 `Implementors` | A list of implementors committed to delivering an implementation of the proposal, when applicable. `N/A` when not applicable and `[]` when there's currently no implementor.
 `Discussions`  | A list of links where major technical discussions regarding this CIP happened. Links should include any discussion before submission, and _must_ include a link to the pull request that created the CIP and any pull request that modifies it.
@@ -113,8 +114,8 @@ For example:
 ---
 CIP: 1
 Title: CIP Process
-Status: Active
 Category: Meta
+Status: Active
 Authors:
     - Frederic Johnson <[email protected]>
     - Sebastien Guillemot <[email protected]>
@@ -134,7 +135,8 @@ Discussions:
     - Original-PR: https://github.com/cardano-foundation/CIPs/pull/366
 ```
 
-> **Note** A reference template is available in [.github/CIP-TEMPLATE.md][CIP-TEMPLATE.md]
+> [!TIP]
+> A reference template is available in [.github/CIP-TEMPLATE.md][CIP-TEMPLATE.md]
 
 ##### Repository Organization
 
@@ -192,15 +194,15 @@ CIPs are licensed in the public domain. More so, they must be licensed under one
 | For software / code | Apache-2.0 - [Apache License, version 2.0][Apache-2.0]                                 |
 | For documentation   | CC-BY-4.0 - [Creative Commons Attribution 4.0 International Public License][CC-BY-4.0] |
 
-> **Warning**
->
+> [!WARNING]
 > All licenses not explicitly included in the above lists are not acceptable terms for a Cardano Improvement Proposal unless a later CIP extends this one to add them.
 
 #### Statuses
 
 CIPs can have three statuses: `Proposed`, `Active` or `Inactive`. [The CIP Process section](#process) highlights how CIPs move through these statuses; no CIP should be given one of these statuses without satisfying the criteria described here below.
 
-> **Note** There is no "draft" status: a proposal which has not been merged (and hence exists in a PR) is a draft CIP. Draft CIPs should include the status they are aiming for on acceptance. Typically, but not always, this will be _'Proposed'_.
+> [!NOTE]
+> There is no "draft" status: a proposal which has not been merged (and hence exists in a PR) is a draft CIP. Draft CIPs should include the status they are aiming for on acceptance. Typically, but not always, this will be _'Proposed'_.
 
 ##### Status: Proposed
 
@@ -244,7 +246,8 @@ This must be subdivided into two sub-sections:
 
     In particular, an implementation that requires a hard-fork should explicitly mention it in its _'Implementation Plan'_.
 
-> **Note** the statuses of `Proposed` and `Active` _both_ require a _Path to Active_ section, making this a _required_ section for all viable proposals.  Even if a CIP is edited or submitted with an `Inactive` status, it may still be helpful to have a `Path to Active` if there are conditions that might lead to its acceptance or implementation.
+> [!NOTE]
+> The statuses of `Proposed` and `Active` _both_ require a _Path to Active_ section, making this a _required_ section for all viable proposals.  Even if a CIP is edited or submitted with an `Inactive` status, it may still be helpful to have a `Path to Active` if there are conditions that might lead to its acceptance or implementation.
 
 #### Categories
 
@@ -271,7 +274,6 @@ These tentatively enlisted categories await CIPs to describe any enlistment rela
 
 Category  | Description
 ---       | ---
-Catalyst  | For proposals affecting Project Catalyst or the Jörmungandr project
 Consensus | For proposals affecting implementations of the Cardano Consensus layer and algorithms
 Network   | Specifications and implementations of Cardano's network protocols and applications
 
@@ -289,7 +291,8 @@ It should be noted that single organisations can no longer represent any ecosyst
 
 Any guidelines for this cooperation should be described by a dedicated CIP whenever possible.  When such a CIP is posted or supersedes another one, it will be entered into the above table in the Categories section.  Participants of enlisted categories should follow the requirements outlined in that CIP and should update such proposals whenever these requirements or relationships change.
 
-> **Warning** A positive review by any enlisted project representative does not constitute a commitment to implement the CIP. It is still the CIP author's responsibility to create an implementation plan and identify implementors.
+> [!WARNING]
+> A positive review by any enlisted project representative does not constitute a commitment to implement the CIP. It is still the CIP author's responsibility to create an implementation plan and identify implementors.
 
 Editors occasionally invite representatives from enlisted categories to speak during review meetings and solicit them for ultimate approvals of proposals in their area of expertise.
 
@@ -305,11 +308,20 @@ Editors occasionally invite representatives from enlisted categories to speak du
 
 ##### 1.a. Authors open a pull request
 
-Proposals must be submitted to the [cardano-foundation/CIPs][Repository] repository as a pull request named after the proposal's title. The pull request title **should not** include a CIP number (and use `?` instead as number); the editors will assign one. Discussions may precede a proposal. Early reviews and discussions streamline the process down the line.
+Proposals must be submitted to the [cardano-foundation/CIPs][Repository] repository as a pull request named after the proposal's title. The pull request title **should not** include a CIP number (and use `?` instead as number); the editors will assign one. Discussions may precede a proposal: early reviews and discussions streamline the process down the line.
 
-> **Note** Pull requests should not include implementation code: any code bases should instead be provided as links to a code repository.
+PRs should not contain commits that also appear in other repository PR's: usually the consequence of re-using a branch in your fork or submitting your work from your fork's `master` branch.  To avoid this, please:
+- Don't submit your PR from your fork's `master` branch.
+- Create a new branch for every pull request that you intend to submit.
 
-> **Note** Proposals addressing a specific CPS should also be listed in the corresponding CPS header, in _'Proposed Solutions'_, to keep track of ongoing work.
+> [!TIP]
+> The CIP title in the pull request should be kept consistent with the CIP header `Title:`.
+
+> [!IMPORTANT]
+> Pull requests should not include implementation code: any code bases should instead be provided as links to a code repository.
+
+> [!NOTE]
+> Proposals addressing a specific CPS should also be listed in the corresponding CPS header, in _'Proposed Solutions'_, to keep track of ongoing work.
 
 ###### Naming CIPs with similar subjects
 
@@ -323,7 +335,16 @@ CIP editors will help determine these common elements and, whenever necessary, r
 
 In the original comment for your pull request, please include a link to the directory or the `README.md` for the CIP in your working branch, so readers and reviewers can easily follow your work.  This makes it easier for editors and the community to read and review your proposal.
 
-> **Note** If this link changes (e.g. from the CIP directory being renamed), please keep this link updated.
+> [!NOTE]
+> If this link changes (e.g. from the CIP directory being renamed), please keep this link updated.
+
+###### Follow a reviewer- and editor-friendly review process
+
+As review progresses:
+- When editors and reviewers submit changes that you accept, commit them from the GitHub UI so these review points are resolved.
+- Even if resolving these in your own environemnt, mark any review points Resolved as they are resolved: otherwise your PR will appear stalled and merging will likely be delayed.
+- **Don't "force push"**: which overwrites commit histories and disrupts change visibility during the review process.  Instead, `git merge` the PR branch back into your local environment: which will preserve any collaborative editing history.
+
 
 ##### 1.b. Authors seek feedback
 
@@ -335,7 +356,8 @@ As much as possible, commenters/reviewers shall remain unbiased in their judgeme
 
 By opening pull requests or posting comments, commenters and authors agree to our [Code of Conduct][CoC]. Any comment infringing this code of conduct shall be removed or altered without prior notice.
 
-> **Note** For acceptability guidelines, including a concise review checklist, see 
+> [!NOTE]
+> For acceptability guidelines, including a concise review checklist, see 
 [CIP Wiki > CIPs for Reviewers & Authors](https://github.com/cardano-foundation/CIPs/wiki/2.-CIPs-for-Reviewers-&-Authors).
 
 #### 2. Editors' role
@@ -356,7 +378,8 @@ A dedicated Discord channel may also be created for some long-running discussion
 
 Once a proposal has reached all requirements for its target status (as explained in [Statuses](#statuses)) and has been sufficiently and faithfully discussed by community members, it is merged with its target status.
 
-> **Warning** Ideas deemed unsound shall be rejected with justifications or withdrawn by the authors. Similarly, proposals that appear abandoned by their authors shall be rejected until resurrected by their authors or another community member.
+> [!WARNING]
+> Ideas deemed unsound shall be rejected with justifications or withdrawn by the authors. Similarly, proposals that appear abandoned by their authors shall be rejected until resurrected by their authors or another community member.
 
 CIPs are generally merged with the status _'Proposed'_ until they meet their _'Path to Active'_ requirements. In some rare cases (mainly when written after the facts and resulting in a broad consensus), proposals may be merged as _'Active'_ immediately.
 
@@ -366,7 +389,8 @@ Each proposal is unique and has a bespoke _'Path to Active'_, which must be revi
 
 Once merged, implementors shall execute the CIP's _'Implementation Plan'_, if any. If a proposal has no implementors or no _'Implementation Plan'_, it may simply remain as _'Proposed'_ in the repository.
 
-> **Warning** It is perfectly fine to submit ideas in the repository with no concrete implementation plan, yet they should be treated as such: ideas.
+> [!WARNING]
+> It is perfectly fine to submit ideas in the repository with no concrete implementation plan, yet they should be treated as such: ideas.
 
 Besides, once all of the _'Path to Active'_ requirements have been met, authors shall make another pull request to change their CIP's status to _'Active'_. Editors may also do this on occasion.
 

CIP-9999/README.md

@@ -1,8 +1,8 @@
 ---
 CIP: 9999
 Title: Cardano Problem Statements
-Status: Active
 Category: Meta
+Status: Active
 Authors:
     - Matthias Benkort <[email protected]>
     - Michael Peyton Jones <[email protected]>
@@ -17,7 +17,8 @@ License: CC-BY-4.0
 
 A Cardano Problem Statement (CPS) is a formalized document for the Cardano ecosystem and the name of the process by which such documents are produced and listed. CPSs are meant to complement CIPs and live side-by-side in the CIP repository as first-class citizens.
 
-> **Note** Read this CIP's number as "CIP minus 1"
+> [!NOTE]
+> Read this CIP's number as "CIP minus 1" (in [tens' complement](https://en.wikipedia.org/wiki/Method_of_complements#Decimal_example))
 
 ## Motivation: why is this CIP necessary?
 
@@ -56,8 +57,8 @@ Field                | Description
 ---                  | ---
 `CPS`                | CPS number (without leading 0), or "\?" before being assigned
 `Title`              | A succinct and descriptive title
-`Status`             | Open \| Solved \| Inactive (..._reason_...)
 `Category`           | One registered or well-known category covering one area of the ecosystem.
+`Status`             | Open \| Solved \| Inactive (..._reason_...)
 `Authors`            | A list of authors' real names and email addresses (e.g. John Doe <[email protected]>)
 `Proposed Solutions` | A list of CIPs addressing the problem, if any
 `Discussions`        | A list of links where major technical discussions regarding this CPS happened. Links should include any discussion before submission, a link to the pull request that created the CPS, and any pull request that modifies it.
@@ -70,8 +71,8 @@ For example:
 ---
 CPS: 1
 Title: The Blockchain Trilemma
-Status: Open
 Category: Consensus
+Status: Open
 Authors:
     - Alice <[email protected]>
     - Bob <[email protected]>
@@ -109,7 +110,8 @@ Open         | Any problem statement that is fully formulated but for which ther
 Solved       | Problems for which a complete solution has been found[^1] and implemented. When solved via one or multiple CIPs, the solved status should indicate it as such: `Solved: by <CIP-XXXX>[,<CIP-YYYY>,...]`.
 Inactive    | The statement is deemed obsolete or withdrawn for another reason. A short reason must be given between parentheses. For example: `Inactive (..._reason_...).
 
-> **Note** There is no "draft" status: a proposal which has not been merged (and hence exists in a PR) is a draft CPS. Draft CPSs should include the status they aim for on acceptance, typically but not always; this will be _'Open'_.
+> [!NOTE]
+> There is no "draft" status: a proposal which has not been merged (and hence exists in a PR) is a draft CPS. Draft CPSs should include the status they aim for on acceptance, typically but not always; this will be _'Open'_.
 
 #### Categories
 
@@ -124,8 +126,7 @@ CPSs are licensed in the public domain. More so, they must be licensed under one
 | For software / code | Apache-2.0 - [Apache License, version 2.0][Apache-2.0]                                 |
 | For documentation   | CC-BY-4.0 - [Creative Commons Attribution 4.0 International Public License][CC-BY-4.0] |
 
-> **Warning**
->
+> [!WARNING]
 > All licenses not explicitly included in the above lists are not acceptable terms for a Cardano Problem Statement unless a later CIP extends this one to add them.
 
 ### The CPS Process