Proposal to revise CIP template sections
Background
Multiple community members have expressed difficulty distinguishing between certain sections in the current CIP template, specifically:
- Motivation vs. Rationale
- Specification vs. Reference Implementation
This redundancy can lead to confusion and potentially redundant content in CIPs. To address this, I propose modifying the CIP template to consolidate these sections.
Proposed changes
1. Combine Motivation and Rationale
Currently, the template includes separate sections for Motivation and Rationale. However, these often contain similar information. I propose merging these into a single section called “Motivation and Rationale” to eliminate redundancy and provide a clearer structure for authors.
Alternatively, this could just be called “Motivation” or “Rationale”.
2. Combine Specification and Reference Implementation
The Specification and Reference Implementation sections often overlap, with the Reference Implementation sometimes serving as a code-based version of the Specification. I propose combining these into a single “Specification and Implementation” section, allowing authors to present the technical details in the most appropriate format (prose, code, or a combination of both).
Alternatively, this could just be called “Specification”.
Benefits
- Simplified structure for CIP authors
- Reduced redundancy in CIP content
- Clearer presentation of ideas for readers
Next steps
If this proposal has enough consensus, I will draft a meta-CIP to modify the template, and maybe CIP-1.
Discussion points
- Are there any drawbacks to combining these sections?
- Should we consider any other modifications to the CIP template?
- How can we ensure backwards compatibility with existing CIPs? Do we need to update existing CIPs?
I’d like to welcome community feedback on this proposal. Please share your thoughts and suggestions in the comments below!
