CPSs: Ensure header and templated section correctness

[Ryun1]

Follow up PR to #1125 addressing formatting issues with existing CPSs.

CPS Validation

Validations applied to /CPS-*/README.md

File level validations:

• line endings are UNIX

yaml header validations:

• all required fields present and in order
• all required fields are expected types/structure (as defined by a JSON schema)
  • including Discussion and Solutions entries as dictionaries, to allow labelling of URLs

Template compliance:

• No H1 headings present
• Required (H2) sections (capitalisation match too)
• Optional H2 sections -- 'Versioning', 'References', 'Appendix', 'Appendices', 'Acknowledgments', 'Acknowledgements'.

[Ryun1]

I still have a few more things to do here
we will need to decide on a specific format for Proposed Solutions as different authors use different structures

[rphair]

we will need to decide on a specific format for Proposed Solutions

From the list of CPS files using Proposed Solutions generated from

grep -i 'proposed solutions' CPS*/README.md | grep -v '\[]$' | sed s/:.*// | sort -u

we have these styles to choose from as precedents (not including the obvious syntax errors):

CPS: 3
Proposed Solutions:
    - CIP-0113: https://github.com/cardano-foundation/CIPs/pull/444

CPS: 5
Proposed Solutions:
  - CIP-0038 (tentative)
  - CIP-0057 (tentative)
  - CIP-0069 (tentative)
  - CIP-0087 (tentative)

CPS: 7
Proposed Solutions:
  - CIP-1694 

CPS: 14
Proposed Solutions:
  - https://github.com/cardano-foundation/CIPs/tree/master/CIP-0114

CPS: 16
Proposed Solutions:
  - CIP-0013: https://github.com/cardano-foundation/CIPs/tree/master/CIP-0013
  - CIP-0099: https://github.com/cardano-foundation/CIPs/tree/master/CIP-0099
  - CIP-0107: https://github.com/cardano-foundation/CIPs/tree/master/CIP-0107
  - CIP-0134: https://github.com/cardano-foundation/CIPs/tree/master/CIP-0134

CPS: 17
Proposed Solutions: 
    ["CIP-0140 : Ouroboros Peras - Faster Settlement"
    ,"CIP-0161 : Ouroboros Phalanx - Breaking Grinding Incentives"
    ]

CPS: 20
Proposed Solutions: 
-   

CPS: 21
Proposed Solutions: 
  ["CIP-0161 : Ouroboros Phalanx - Breaking Grinding Incentives"]

Right now rendering on GitHub is our only priority because Proposed Solutions: isn't displayed on cips.cardano.org (we'd suggested it for a search index field in cardano-foundation/cf-cip-frontend#60) but with no constructive response yet). Therefore I would suggest that we follow the example of CPS-0016 because:

• there will be an indefinite wait for any progress on that web UI issue
• we would therefore have to make do with the "links" to related proposals we have on GitHub itself (the absolute URIs lined up horizontally are cumbersome, but at least they work)
• the YAML syntax CIP editors including @Crypto2099 agreed upon at the time CPS-0016 was drafted was the most convenient for readers to click in immediately to related proposals in the header.

I would further propose that the corresponding field in CIPs be structured in the same way... with both CIP-0001 and CIP-9999 updated accordingly to emphasise this link syntax as a validation requirement (right now I think it's offered more as an optional feature).

This allows all existing CPS headers to be easily corrected, and will also allow linking to CIP candidates because authors can also link to an unmerged PR and also require a quoted ? after the CIP number in this case.... the latter case @Ryun1 therefore a good item to add to your validation script because this would be difficult to check manually.

---

p.s. to play my own devil's advocate here, there is another argument for leaving the structure loose... an approach that would naturally make more sense if we were able to make improvements to cips.cardano.org ourselves and put these things into a presentation layer rather than the source text... I'll refer to @michaelpj's words on the subject which I found persuasive about a very similar CIP formatting issue (cc @perturbing):

• CIP-0001 | Structure and template revisions #730 (comment)

[Ryun1]

example of CPS-0016

I agree 100%
this is a nice way to represent it

I would further propose that the corresponding field in CIPs be structured in the same way...

I agree 100% again
I will make this effort in this PR and in #1125

[rphair]

Looks great so far @Ryun1 - I guess you're moving through CPSs in numerical order but the new templates, CIP 9999 updates, and changes so far are all consistent and well expressed; just post again when you're done committing CPS updates so we can sign off or make further updates.

[rphair]

@Ryun1 @perturbing - both these related update proposals outlined & readily confirmed at the CIP meeting today. 🎉

[Ryun1]

okay thats all CPSs addressed for the moment

the only thing I may change is Original pull request isnt too descriptive
I feel CPS-00XX original pull request may be a better precedent to set

[rphair]

CPS-00XX original pull request may be a better precedent to set

I think people will reflexively push back about this (by not complying) because of its redundancy most of the time. The set of Discussions: links as a whole will be dominated by self pull request links... and so the term Original pull request will 1) be concise and accurate without adding the CIP or CPS tag (since there will be a commonly recognised default), and 2) not have to be updated again when a CIP/CPS is assigned a number.

Having to include a CPS or CIP tag every time would therefore almost always be unnecessary and would introduce a common error and/or one more thing @Ryun1 to parse & check in your validator.

However I do think that enough flexibility to tag some other CIP's or CPS's original pull request in the Disucssions: list could be very useful sometimes (especially among related CIPs, or between a corresponding CIP + CPS).

[rphair]

@Ryun1 I might have missed something all along because in #1125 (comment) you had used the term "Enforced capitalisation" which only now I realised was part of a longer term "Enforced capitalisation consistency".

I've been assuming, and so writing my grep queries, that all the H2 document headings are "titles" (with anything after the : a "subtitle") and so should have every word capitalised. Currently we're not seeing that with the CPS text in the branch at this time:

$ egrep -n '^#\s|^##\s' CPS-*/README.md | egrep -v 'Abstract$|Problem$|Use Cases$|Goals$|Open Questions$|References$|Acknowledgments$|Acknowledgements$|Copyright$'

CPS-0003/README.md:36:## Use cases
CPS-0007/README.md:55:## Use cases
CPS-0008/README.md:32:## Use cases
CPS-0010/README.md:168:## Use cases
CPS-0011/README.md:36:## Use cases
CPS-0012/README.md:97:## Use cases
CPS-0013/README.md:37:## Use cases
CPS-0013/README.md:90:## Open questions
CPS-0014/README.md:53:## Use cases
CPS-0016/README.md:39:## Use cases
CPS-0017/README.md:64:## Use cases
CPS-0017/README.md:121:## Open questions
CPS-0018/README.md:92:## Use cases
CPS-0018/README.md:120:## Open questions
CPS-0020/README.md:118:## **References**
CPS-0022/README.md:96:## Open Questions 

We should first confirm that these titles will have all words capitalised: unless I've misunderstood something.

• I also think it's fair to leave the question to you (as the validator architect) whether to standardise & validate the capitalisation of keys in the YAML header as well... personally I believe it will be even more important there, since it's more likely that parsers will have to digest that material.

[Ryun1]

@rphair

Having to include a CPS or CIP tag every time would therefore almost always be unnecessary and would introduce a common error and/or one more thing @Ryun1 to parse & check in your validator.

good point, agreed lets keep it as Original pull request

We should first confirm that these titles will have all words capitalised: unless I've misunderstood something.

good spot, Id missed this
I will ensure correct capitalisation of headers and Yaml header fields

[rphair]

@Ryun1 (cc @perturbing) following up on YAML keywords for Discussions:... a good example case to help clarify when CIP tags & descriptions are useful vs. redundant (also considering editing burden during CIP review process):

• CIP-0175? | SPO Governance Voting with Calidus Keys #1140 (comment)

[rphair]

good point, agreed lets keep it as Original pull request

Also let's consider using the concise PR instead of pull request to reduce the typographical burden and keep signal-to-noise ratio high. The fact that these links will always be clickable would reduce the consequences in case some reader might not know what PR stands for. 😅

I've modified my suggestion here so we can see how it would look: #1140 (comment) - cc @Cerkoryn

[rphair]

it keeps looking better @Ryun1 ... let us know when it's ready for review ⭐

[Ryun1]

@rphair it is nearly done 💪

one final query
what is the correct order for header fields?

CPS, Title, Category, Status
OR
CPS, Title, Status, Category

I have found it inconsistent across CPSs, CIPs and their templates
I don't mind which way around we go, but best to decide on one

[rphair]

that's awesome @Ryun1 ⭐ ... we rationalised this a couple years ago with CIP 1 & -1 and the templates themselves: they all run

CIP: / CPS:
Title:
Category:
Status:

As you've seen, the documents themselves don't always confirm to this. Since YAML itself considers the ordering irrelevant we left the order arbitrary by default at the time. I certainly don't have a problem automatically standardising it now. 😎

[rphair]

@Ryun1 if that last commit takes care of it all (?) I can perhaps double-check it before tomorrow's meeting if ready some time today... otherwise I'll review / approve / proofread it ASAP after you confirm this later.