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

Update EIP-1: Clarified use of all-capitalized key words and declared non-usage for EIP-1 #8784

Closed

Conversation

jwmeyert7
Copy link

@jwmeyert7 jwmeyert7 commented Aug 4, 2024

Proposed Changes to EIP-1

This pull request proposes modifications to EIP-1 to clarify the use of all-capitalized key words as specified in RFC 2119 and RFC 8174 for new EIPs and for EIP-1 itself. The key changes include:

  1. Specification Section Addition:
    • Added a new Specification section at the top of EIP-1, declaring that all capitalized key words as described in RFC 2119 and RFC 8174 are deliberately not in use in this document.
    • Added a section in the Style Guide for how to make this choice on a case by case basis depending on EIP type and how to declare the choice made in the EIP.

Rationale and Benefits:

  • Clarity: Ensures that the use of RFC 2119 key words is explicitly stated in new EIPs and EIP-1 itself, improving the reader's understanding of the document's intent and style.
  • Consistency: Encourages EIP authors to use these key words deliberately and correctly or not at all, enhancing the quality of technical documentation while maintaining flexibility.
  • Transparency: Clearly stating the choice at the beginning of the EIP avoids any confusion later in the document and mitigates casual usage.
  • Exemplification: Declaring usage up front in EIP-1 exemplifies for other EIPs the correct way to treat this and the benefits of clarity in doing so.

Challenges:

  • Verification: Ensuring that the current usage in EIP-1 adheres to the specified choice might require a more detailed review depending on EIP-1's original authors intent. In this pull request I have combed through and modified them all to be lowercase as I declared them not in use in the Specifications.
  • Ensuring Clarity in Specifications: declaring the absence of RFC 2119 usage may be distracting to readers and ultimately unnecessary. It may be easier to simply have EIP-1 require authors make a choice and then only declare it if it is in use.

By clarifying the use of all-capitalized key words, this proposal aims to improve the readability and precision of Ethereum’s technical documentation while still allowing transparency and choice for EIP writers.

@jwmeyert7 jwmeyert7 requested a review from eth-bot as a code owner August 4, 2024 22:42
@github-actions github-actions bot added c-update Modifies an existing proposal t-process labels Aug 4, 2024
@eth-bot
Copy link
Collaborator

eth-bot commented Aug 4, 2024

File EIPS/eip-1.md

Requires 3 more reviewers from @axic, @g11tech, @gcolvin, @lightclient, @SamWilsn, @xinbenlv

@eth-bot eth-bot added the e-consensus Waiting on editor consensus label Aug 4, 2024
@eth-bot eth-bot changed the title Clarified use of all-capitalized key words and declared non-usage for EIP-1 Update EIP-1: Clarified use of all-capitalized key words and declared non-usage for EIP-1 Aug 4, 2024
@jwmeyert7 jwmeyert7 closed this Aug 4, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
c-update Modifies an existing proposal e-consensus Waiting on editor consensus t-process
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants