Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

CIP-1694 | Move Acknowledgements into optional section #763

Merged

Conversation

rphair
Copy link
Collaborator

@rphair rphair commented Feb 20, 2024

We had a request on Discord (@klntsky) which was well received: to move "workshop participants" (and maybe sometimes lists of minor co-authors) to the ends of CIP documents as per the optional sections legitimised in #730.

This is also mandated by SEO principles like "source ordering" which is still an issue for properly indexing big documents with lots of names or code at the beginning.

Also CIP-0001 / CIP-9999 are updated to clear the way for similar Acknowledgements sections to be added in future CIPs / CPSs. CIP-1694 is the one with the widest audience so let's clear this one first & then I/we can submit one more PR to update all others to follow suit: after confirming this first change is well received by the community.

@Ryun1 @Crypto2099 you've been managing some CIP relevant workshops so maybe we can also assemble a list of other documents to update in this PR discussion thread. Another clue would be greping for the <details> tag to create the "accordion" sections.

@Hornan7 note this also updates the French version, but the commit hash is the same since the material isn't being re-translated. edit, p.s. French version has been removed from this PR since the English copy is changing a bit.

p.s. since this has long been associated with the Ledger Team perhaps @lehins @WhatisRT you would also confirm this particular change to CIP-1694 itself.

p.p.s. the "shortest common substring" algorithm used by diff doesn't always produce a straightforward result for moving one single large block of text elsewhere in a file. The only change submitted in 73c0391 is to move the entire #### Acknowledgements section from near the beginning (before the Motivation) to near the end (before the Copyright).


(updated CIP-1694 in English)
(updated CIP-0001)
(updated CIP-9999)

@rphair rphair added the Update Adds content or significantly reworks an existing proposal label Feb 20, 2024
Copy link
Collaborator Author

@rphair rphair left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@lehins @WhatisRT @JaredCorduan - Editors in the CIP meeting today considered how important (politically and personally) it is for the community to be aware of these contributors, even in cases where nontechnical or hurried readers won't see the whole document.

We decided in these cases CIPs / CPSs can include a link to a latter Acknowledgements section "above the fold" by author's preference. I believe this can be done in the Abstract because community contribution can be considered part of a document's summary.

Please have a look at this suggestion and let us know if you think it's acceptable or if you would recommend different markup:

p.s. @Hornan7 if we do change the English markup I'll drop the French translation from this PR so you can provide the translation separately as usual.

CIP-1694/README.md Show resolved Hide resolved
@WhatisRT
Copy link
Contributor

Looks good, especially with the added reference to the Acknowledgements section.

@Hornan7
Copy link
Contributor

Hornan7 commented Feb 26, 2024

I'll make sure the French version is updated within 3 days of the merge.

@rphair
Copy link
Collaborator Author

rphair commented Mar 1, 2024

@Ryun1 @Crypto2099 adding Last Check for next meeting since this has author & community approval & I believe just needs to be double checked by the editors.

@rphair rphair added the State: Last Check Review favourable with disputes resolved; staged for merging. label Mar 1, 2024
Copy link
Collaborator

@Ryun1 Ryun1 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree that this is a very sensible change, thanks for pushing forward with this @rphair 💪

Copy link
Collaborator

@Crypto2099 Crypto2099 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These changes make sense and will make the CIPs much more machine-readable (i.e. search engine optimization) while formalizing co-author and contributor acknowledgements as part of the CIP/CPS process.

@rphair rphair merged commit 7631f32 into cardano-foundation:master Mar 5, 2024
@rphair
Copy link
Collaborator Author

rphair commented Mar 5, 2024

epilogue: pinging other devs on Discord (in this post) to see which other proposals we might want to do this with (cc @Ryun1 @Crypto2099 @klntsky).

rphair pushed a commit that referenced this pull request Mar 7, 2024
- Correction to the French version related to PR #763
- From commit "Move Acknowledgements into optional section"
- Fixed additional typo in the "Copyright" section of the French version
@rphair rphair removed the State: Last Check Review favourable with disputes resolved; staged for merging. label Sep 3, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Update Adds content or significantly reworks an existing proposal
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants