search

cardano-foundation / CIPs

Cardano Improvement Proposals (CIPs)
https://cips.cardano.org/
Creative Commons Attribution 4.0 International
517 stars 322 forks source link

README titles out of sync with document titles #900

Open rphair opened 2 months ago

rphair commented 2 months ago

Result of investigating https://github.com/cardano-foundation/CIPs/pull/854#discussion_r1741144968.

I thought it would be an easy check & fix for the small number of CIP titles that might be disparate with the titles in the repository front page table.

But even when ignoring case comparisons (a substantial source of difference & maybe even a problem for some kinds of indexing / parsing) there are quite a few that apparently drifted in the review process:

$ diff -i cip-from-docs cip-from-readme
1c1
< CIP-0001: Cardano Improvement Proposals
---
> CIP-0001: CIP process
15c15
< CIP-0015: Registration Transaction Metadata Format
---
> CIP-0015: Catalyst Registration Transaction Metadata Format
35,36c35,36
< CIP-0035: Changes to Plutus Core
< CIP-0036: Catalyst Registration Transaction Metadata Format (Updated)
---
> CIP-0035: Plutus Core Evolution
> CIP-0036: Catalyst Registration Transaction Metadata Format
39c39
< CIP-0042: New Plutus Builtin serialiseData
---
> CIP-0042: New Plutus Builtin: serialiseBuiltinData
46c46
< CIP-0057: Plutus Contract Blueprint
---
> CIP-0057: Plutus Smart-Contract Blueprint
52c52
< CIP-0069: Script Signature Unification
---
> CIP-0069: Plutus Script Type Uniformization
54,55c54,55
< CIP-0072: Cardano dApp Registration & Discovery
< CIP-0074: Set minPoolCost to 0
---
> CIP-0072: DApp Registration
> CIP-0074: Set min-pool-cost to 0
66c66
< CIP-0094: On-chain SPO polls
---
> CIP-0094: SPO On-chain Polls
70c70
< CIP-0101: Integration of `keccak256` into Plutus
---
> CIP-0101: Integration of keccak256 into Plutus
79c79
< CIP-0110: Plutus v1 Script References
---
> CIP-0110: Plutus v1 compatible script references
83c83
< CIP-0116: Standard JSON encoding for Domain Types
---
> CIP-0116: Universal JSON Encoding for Domain Types
92c92
< CIP-1694: A First Step Towards On-Chain Decentralized Governance
---
> CIP-1694: A proposal for entering the Voltaire phase
$ diff -i cps-from-docs cps-from-readme
9c9
< CPS-0014: Register of CBOR Tags for Cardano Data structures
---
> CPS-0014: Register of CBOR Tags

This above is a complete list of differences at this time but before rushing ahead to change them I wanted to get the feeling from editors & community how much of an issue they think this is. In many of these cases I also wouldn't be sure whether the README title or the document title would be better.

Likely before the end of the year @Ryun1 and/or I will be producing some automation that will build this table from the source documents anyway... which would confirm that the document titles are canonical by default.

My inclination is therefore to declare the differences above "cosmetic" but still keep this issue open until some GitHub automation produces a character-perfect table.

To confirm that's OK (or not) I wanted to sample opinions from people who work with CIPs (including rendering them on other web sites) whether they think these differences should be resolved right away: @Crypto2099 @KtorZ @katomm @fill-the-fill @WhatisRT @lehins @zliu41 @perturbing @fallen-icarus @Hornan7

Hornan7 commented 2 months ago

Any decisions made about whether to move forward with this will have no negative impact on my work around the CIPs. So I'm okay with any outcome. 😃👍

fallen-icarus commented 2 months ago

I don't think the fix needs to be rushed. Personally, I use the CIP numbers more than the titles when navigating/referencing, and the titles seem "close enough". I didn't even notice some of the titles were out of sync :sweat_smile:

rphair commented 2 months ago

This is one CIP that should be retitled ASAP as in the repo README:

< CIP-0001: Cardano Improvement Proposals
---
> CIP-0001: CIP process

Until then, the Cardano Improvement Proposals (CIPs) section of the Dev Portal will have a first heading of (1) Cardano Improvement Proposals... it would be more meaningful for readers (as it is on the CIP repo README) to have the first heading be CIP Process. See: https://developers.cardano.org/docs/governance/cardano-improvement-proposals/CIP-0001

rphair commented 1 month ago

https://github.com/cardano-foundation/CIPs/issues/900#issuecomment-2332955740 is fixed by https://github.com/cardano-foundation/CIPs/pull/924.