Add description field to the EIP header by axic · Pull Request #3706 · ethereum/EIPs

axic · 2021-08-06T19:39:31Z

The header:

Twitter before:

Twitter after:

Could also render the description prominently after the header.

MicahZoltu

Recommend removing the Simple Summary from the template and EIP-1, as this would be the new place to put that content.

I generally approve, but would like to see the Simple Summary removed along with the introduction of a description metadata field.

EIPS/eip-1.md

eip-template.md

axic · 2021-08-07T13:33:22Z

Recommend removing the Simple Summary from the template and EIP-1, as this would be the new place to put that content.

I generally approve, but would like to see the Simple Summary removed along with the introduction of a description metadata field.

Absolutely, that would be the goal, but decided to keep the first step simple until there's a general agreement on this.

Could also render the description prominently after the header.

My main question right now is how to render it on the page:

only part of the header (as in the PR now)
before the header in large text
after the header in large text
add a new section (like simple summary), but call it Description
both 1) and one of 2) to 4)

MicahZoltu · 2021-08-08T03:46:31Z

I care less about answering the "how it is rendered" question right now, as that is something we can pretty easily/freely iterate on after this change I think. I'm fine with starting out with something simple and then improving it later.

MicahZoltu · 2021-08-08T03:47:05Z

Absolutely, that would be the goal, but decided to keep the first step simple until there's a general agreement on this.

I would like to see that happen in this PR, not a future PR. I dislike the idea of having a period of time where we have both a description and a ## Simple Summary

axic · 2021-08-08T11:04:07Z

Absolutely, that would be the goal, but decided to keep the first step simple until there's a general agreement on this.

I would like to see that happen in this PR, not a future PR. I dislike the idea of having a period of time where we have both a description and a ## Simple Summary

I planned to do it in this PR, but did not wanted to bring extra work to myself before this field is agreed on.

axic · 2021-08-10T11:02:17Z

Some variations:

MicahZoltu · 2021-08-10T14:26:40Z

I like 2.

lightclient · 2021-08-10T16:42:09Z

I like both 1 and 2. In terms of the actual text in the templates, I don't mind too much. I'm on board with the change in general though (it will be great to not repeat the EIP number a dozen times in the social thumbnail!)

axic · 2021-08-12T10:36:15Z

@MicahZoltu should be ready to merge, but let me know if you want to remove the commit for 2718.

MicahZoltu · 2021-08-15T11:21:16Z

EIPS/eip-2718.md

 ---
 eip: 2718
 title: Typed Transaction Envelope
+description: Defines a new transaction type that is an envelope for future transaction types.


Simple Summary should be removed with the inclusion of description. I think.

Right. My question was do you want to touch this file in this PR or not?

I'm fine with 2718 getting updated as a "first example" in this PR.

Ok, also removed the section.

MicahZoltu · 2021-08-15T11:22:18Z

eip-template.md

 ---
 eip: <to be assigned>
 title: <EIP title>
+description: <Provide a simplified and layman-accessible explanation of the EIP.>


I think it would be valuable to include this text or similar, but not a hard requirement if others disagree:

Imagine an email subject line, GitHub PR title, or forum post title.

I don't want to argue too much about it, but what is the title then?

Title is a few words, not a complete sentence.

King Micah

Description is one full (short) sentence.

The benevolent dictator of the EIPs repository.

Abstract is multi-sentence (short paragraph) technical summary.

Micah is the unelected, self assigned dictator of the EIPs repository. They rule by way of blocking an PRs they don't like and merging things they like without waiting for agreement from anyone else. Micah's power can be taken away by someone else volunteering to take on the responsibilities of shepherding the EIP's repository."

Another way to look at it is that a Title is what you would use in a sentence when referring to the EIP. "We should implement the EVM Object Format in Shanghai." The description is what you would use to jog someone's memory as to what the EIP is. "What is the EVM Object Format?" "It is the EIP that Establishes contract versioning by way of a leading bytecode sequence." "Ah, right, I remember that one."

I think actually your description is much better suited as opposed to the examples you gave :)

title: <Title is a few words, not a complete sentence.> description: <Description is one full (short) sentence.> abstract: <Abstract is multi-sentence (short paragraph) technical summary.>

Works for me. :)

axic · 2021-08-16T15:57:13Z

@MicahZoltu this still needs a manual merge from you 😅

axic · 2021-08-17T09:10:28Z

Blocked by ethereum/eipv#28 😭

All eyes are on you @lightclient 🙏

This has been removed from EIP-1 on 15-09-2019 in the PR ethereum#2186.

EIPS/eip-1.md

eip-template.md

* Add description field to the EIP header * Update 2718 * Move description rendering to below the title * Remove the simple summary from the template This has been removed from EIP-1 on 15-09-2019 in the PR ethereum#2186. * Update title/description/abstract with new recommendation * Mention length limit of description

axic requested review from MicahZoltu and lightclient August 6, 2021 19:58

MicahZoltu suggested changes Aug 7, 2021

View reviewed changes

EIPS/eip-1.md Outdated Show resolved Hide resolved

eip-template.md Outdated Show resolved Hide resolved

lightclient approved these changes Aug 10, 2021

View reviewed changes

axic force-pushed the description-header branch from a8508b6 to 58af7c5 Compare August 11, 2021 10:55

axic requested a review from MicahZoltu August 11, 2021 10:57

MicahZoltu reviewed Aug 15, 2021

View reviewed changes

axic mentioned this pull request Aug 16, 2021

Switch EOF EIPs to Review #3717

Merged

axic force-pushed the description-header branch from 58af7c5 to 4c91216 Compare August 16, 2021 12:03

MicahZoltu approved these changes Aug 16, 2021

View reviewed changes

axic force-pushed the description-header branch from 7807444 to 27e2844 Compare August 16, 2021 13:41

axic marked this pull request as ready for review August 16, 2021 13:46

axic force-pushed the description-header branch from 27e2844 to 8e80f46 Compare August 16, 2021 13:48

eth-bot enabled auto-merge (squash) August 16, 2021 13:49

axic force-pushed the description-header branch from 8e80f46 to 3b5cd36 Compare August 17, 2021 19:51

axic added 4 commits August 17, 2021 22:24

Add description field to the EIP header

4f2a26e

Update 2718

c3a2727

Move description rendering to below the title

42324cc

Remove the simple summary from the template

b3ae346

This has been removed from EIP-1 on 15-09-2019 in the PR ethereum#2186.

axic force-pushed the description-header branch from 3b5cd36 to 617b06d Compare August 17, 2021 21:24

axic requested review from MicahZoltu and lightclient August 17, 2021 21:25

axic force-pushed the description-header branch from 617b06d to 1de8caf Compare August 17, 2021 21:25

lightclient reviewed Aug 17, 2021

View reviewed changes

EIPS/eip-1.md Outdated Show resolved Hide resolved

eip-template.md Outdated Show resolved Hide resolved

axic added 2 commits August 17, 2021 22:43

Update title/description/abstract with new recommendation

e371a09

Mention length limit of description

9e91d4a

axic force-pushed the description-header branch from 1de8caf to 9e91d4a Compare August 17, 2021 21:43

axic requested a review from lightclient August 17, 2021 21:44

MicahZoltu disabled auto-merge August 17, 2021 23:04

MicahZoltu merged commit 1bfcf0c into ethereum:master Aug 17, 2021

axic deleted the description-header branch August 17, 2021 23:08

ethereum deleted a comment Aug 21, 2021

axic mentioned this pull request Sep 19, 2021

EIP-3855: Review mode #3983

Merged

This was referenced Nov 11, 2021

Remove the simple summary from the template #3564

Closed

Add simple summary to eip-1 #3565

Closed

wjmelements mentioned this pull request Mar 24, 2022

Eip 3651: Stagnant -> Review #4925

Merged

wjmelements added a commit to wjmelements/EIPs that referenced this pull request Mar 24, 2022

move simple summary to description, per ethereum#3706

df3e7d8

eth-bot pushed a commit that referenced this pull request Mar 24, 2022

move simple summary to description, per #3706 (#4940)

ed6e9e1

PowerStream3604 pushed a commit to PowerStream3604/EIPs that referenced this pull request May 19, 2022

move simple summary to description, per ethereum#3706 (ethereum#4940)

9c54b5c

Conversation

axic commented Aug 6, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

MicahZoltu left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

axic commented Aug 7, 2021

Uh oh!

MicahZoltu commented Aug 8, 2021

Uh oh!

MicahZoltu commented Aug 8, 2021

Uh oh!

axic commented Aug 8, 2021

Uh oh!

axic commented Aug 10, 2021

Uh oh!

MicahZoltu commented Aug 10, 2021

Uh oh!

lightclient commented Aug 10, 2021

Uh oh!

axic commented Aug 12, 2021

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

axic commented Aug 16, 2021

Uh oh!

axic commented Aug 17, 2021

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

axic commented Aug 6, 2021 •

edited

Loading