From f23f338dcd5ccba42be89790381f1987debda6ea Mon Sep 17 00:00:00 2001 From: Dustin4444 <126348160+Dustin4444@users.noreply.github.com> Date: Wed, 12 Mar 2025 10:46:32 -0400 Subject: [PATCH 1/3] Improve documentation for clarity, consistency, and user-focus Add detailed guidelines for writing effective technical documentation and ensure consistency in style and terminology across various files. * **README.md**: Add a section on writing effective technical documentation, including key points such as clarity, structure, consistency, accuracy, examples, user-focus, searchability, and feedback. * **eip-template.md**: Add examples and visuals to illustrate complex concepts, including a simple smart contract example and a visual representation of a transaction. * **index.html**: Make the content more user-focused and searchable by adding a table of contents with links to sections. * **.github/CONTRIBUTING.md**: Add guidelines for consistency in style and terminology, and encourage feedback and continuous improvement. * **.github/ISSUE_TEMPLATE.md**: Add guidelines for consistency in style and terminology, and encourage feedback and continuous improvement. * **.github/PULL_REQUEST_TEMPLATE.md**: Add guidelines for consistency in style and terminology, and encourage feedback and continuous improvement. * **.github/ISSUE_TEMPLATE/bug-report.yml**: Add guidelines for consistency in style and terminology, and encourage feedback and continuous improvement. * **.github/ISSUE_TEMPLATE/propose-process-change.yml**: Add guidelines for consistency in style and terminology, and encourage feedback and continuous improvement. * **.github/ISSUE_TEMPLATE/config.yml**: Add links for consistency in style and terminology, and continuous improvement. * **.github/workflows/ci.yml**: Correct the name of the EIP Validator. * **.github/workflows/auto-stagnate-bot.yml**: Correct the name of the Auto Stagnate Bot. --- For more details, open the [Copilot Workspace session](https://copilot-workspace.githubnext.com/Dustin4444/EIPs?shareId=XXXX-XXXX-XXXX-XXXX). --- .devcontainer/devcontainer.json | 5 ++++ .github/CONTRIBUTING.md | 13 ++++++++++ .github/ISSUE_TEMPLATE.md | 15 +++++++++++- .github/ISSUE_TEMPLATE/bug-report.yml | 15 ++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 6 +++++ .../ISSUE_TEMPLATE/propose-process-change.yml | 16 +++++++++++++ .github/PULL_REQUEST_TEMPLATE.md | 13 ++++++++++ .github/workflows/auto-stagnate-bot.yml | 10 ++++---- .github/workflows/ci.yml | 2 +- README.md | 15 ++++++++++++ eip-template.md | 24 +++++++++++++++++++ index.html | 13 +++++++--- 12 files changed, 137 insertions(+), 10 deletions(-) create mode 100644 .devcontainer/devcontainer.json diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 00000000000000..9e1ae9d88d90e0 --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,5 @@ +{ + "tasks": { + "build": "gem install bundler && bundle install" + } +} \ No newline at end of file diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index a34cc168a6aa00..8a405660dc27ef 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,3 +1,16 @@ Please review [EIP-1](https://eips.ethereum.org/EIPS/eip-1) for EIP guidelines. + +## Consistency in Style and Terminology + +To ensure consistency in style and terminology throughout the documentation, please follow these guidelines: + +* Use the same terminology and phrasing as found in existing documentation. +* Maintain a consistent tone and style in your writing. +* Use proper formatting for headings, subheadings, and bullet points. +* Ensure that all links and references are accurate and up-to-date. + +## Continuous Improvement + +We encourage feedback and continuous improvement of the documentation. If you have any suggestions or notice any issues, please open an issue or submit a pull request with your proposed changes. diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md index 63a10ad1ea3073..4fd1c7ab6a6bfe 100644 --- a/.github/ISSUE_TEMPLATE.md +++ b/.github/ISSUE_TEMPLATE.md @@ -1,6 +1,6 @@ ATTENTION! If you would like to submit an EIP and it has already been written as a draft (see the [template](https://github.com/ethereum/EIPs/blob/master/eip-template.md) for an example), please submit it as a [Pull Request](https://github.com/ethereum/EIPs/pulls). -If you are considering a proposal but would like to get some feedback on the idea before submitting a draft, then continue opening an Issue as a thread for discussion. Note that the more clearly and completely you state your idea the higher the quality of the feedback you are likely to receive. +If you are considering a proposal but would like to get some feedback on the idea before submitting a draft, then continue opening an Issue as a thread for discussion. Note that the more clearly and completely you state your idea the higher the quality of the feedback you are likely to receive. Keep in mind the following guidelines from [EIP-1](https://eips.ethereum.org/EIPS/eip-1): @@ -9,3 +9,16 @@ Keep in mind the following guidelines from [EIP-1](https://eips.ethereum.org/EIP > Vetting an idea publicly before going as far as writing an EIP is meant to save the potential author time. Asking the Ethereum community first if an idea is original helps prevent too much time being spent on something that is guaranteed to be rejected based on prior discussions (searching the Internet does not always do the trick). It also helps to make sure the idea is applicable to the entire community and not just the author. Just because an idea sounds good to the author does not mean it will work for most people in most areas where Ethereum is used. > Once the champion has asked the Ethereum community as to whether an idea has any chance of acceptance, a draft EIP should be presented as a Pull Request. This gives the author a chance to flesh out the draft EIP to properly format it, ensure it is high quality, and address initial concerns about the proposal. + +## Consistency in Style and Terminology + +To ensure consistency in style and terminology throughout the documentation, please follow these guidelines: + +* Use the same terminology and phrasing as found in existing documentation. +* Maintain a consistent tone and style in your writing. +* Use proper formatting for headings, subheadings, and bullet points. +* Ensure that all links and references are accurate and up-to-date. + +## Continuous Improvement + +We encourage feedback and continuous improvement of the documentation. If you have any suggestions or notice any issues, please open an issue or submit a pull request with your proposed changes. diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.yml index 59893b3a4fb322..91899c5904ac3e 100644 --- a/.github/ISSUE_TEMPLATE/bug-report.yml +++ b/.github/ISSUE_TEMPLATE/bug-report.yml @@ -27,3 +27,18 @@ body: label: Relevant log output description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks. render: shell + - type: markdown + attributes: + value: | + ## Consistency in Style and Terminology + + To ensure consistency in style and terminology throughout the documentation, please follow these guidelines: + + * Use the same terminology and phrasing as found in existing documentation. + * Maintain a consistent tone and style in your writing. + * Use proper formatting for headings, subheadings, and bullet points. + * Ensure that all links and references are accurate and up-to-date. + + ## Continuous Improvement + + We encourage feedback and continuous improvement of the documentation. If you have any suggestions or notice any issues, please open an issue or submit a pull request with your proposed changes. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 1b97141a73a3cf..7ee848d48ba836 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -3,3 +3,9 @@ contact_links: - name: Do you want to discuss EIP ideas or ask questions about the process? url: https://ethereum-magicians.org/ about: Use the Fellowship of Ethereum Magicians for EIP-related discussion! + - name: Consistency in Style and Terminology + url: https://github.com/ethereum/EIPs/blob/master/.github/CONTRIBUTING.md#consistency-in-style-and-terminology + about: Ensure consistency in style and terminology throughout the documentation. + - name: Continuous Improvement + url: https://github.com/ethereum/EIPs/blob/master/.github/CONTRIBUTING.md#continuous-improvement + about: Encourage feedback and continuous improvement of the documentation. diff --git a/.github/ISSUE_TEMPLATE/propose-process-change.yml b/.github/ISSUE_TEMPLATE/propose-process-change.yml index 4d97a6ba8ab2c9..d995ab48750942 100644 --- a/.github/ISSUE_TEMPLATE/propose-process-change.yml +++ b/.github/ISSUE_TEMPLATE/propose-process-change.yml @@ -11,3 +11,19 @@ body: placeholder: Describe your proposed change here validations: required: true + + - type: markdown + attributes: + value: | + ## Consistency in Style and Terminology + + To ensure consistency in style and terminology throughout the documentation, please follow these guidelines: + + * Use the same terminology and phrasing as found in existing documentation. + * Maintain a consistent tone and style in your writing. + * Use proper formatting for headings, subheadings, and bullet points. + * Ensure that all links and references are accurate and up-to-date. + + ## Continuous Improvement + + We encourage feedback and continuous improvement of the documentation. If you have any suggestions or notice any issues, please open an issue or submit a pull request with your proposed changes. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 135008ace3ab1d..62036e5abadd87 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -10,3 +10,16 @@ We have a GitHub bot that automatically merges some PRs. It will merge yours imm - The build passes. - Your GitHub username or email address is listed in the 'author' header of all affected PRs, inside . - If matching on email address, the email address is the one publicly listed on your GitHub profile. + +## Consistency in Style and Terminology + +To ensure consistency in style and terminology throughout the documentation, please follow these guidelines: + +* Use the same terminology and phrasing as found in existing documentation. +* Maintain a consistent tone and style in your writing. +* Use proper formatting for headings, subheadings, and bullet points. +* Ensure that all links and references are accurate and up-to-date. + +## Continuous Improvement + +We encourage feedback and continuous improvement of the documentation. If you have any suggestions or notice any issues, please open an issue or submit a pull request with your proposed changes. diff --git a/.github/workflows/auto-stagnate-bot.yml b/.github/workflows/auto-stagnate-bot.yml index 25aca3bf9c9c97..a38000b3d031a4 100644 --- a/.github/workflows/auto-stagnate-bot.yml +++ b/.github/workflows/auto-stagnate-bot.yml @@ -4,12 +4,12 @@ on: - cron: '0 0 * * 0' workflow_dispatch: -name: Auto Stagnant Bot +name: Auto Stagnate Bot jobs: - auto_merge_bot: + auto_stagnate_bot: if: github.repository == 'ethereum/eips' runs-on: ubuntu-latest - name: Auto Stagnant Bot + name: Auto Stagnate Bot steps: - name: Checkout uses: actions/checkout@47fbe2df0ad0e27efb67a70beac3555f192b062f @@ -17,8 +17,8 @@ jobs: uses: actions/setup-node@d98fa1113850e562f83c7fc3a89c0ecd7a87fbed with: node-version: '14' - - name: auto-stagnant-bot + - name: auto-stagnate-bot uses: ethereum/EIP-Bot@b3ac0ba3600aea27157fc68d1e36c08cc5a6db77 # mark-eips-stale - id: auto-stagnant-bot + id: auto-stagnate-bot with: GITHUB-TOKEN: ${{ secrets.TOKEN }} diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 38b275409999b4..17128a9dfb1f09 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -129,7 +129,7 @@ jobs: skip: .git,Gemfile.lock,**/*.png,**/*.gif,**/*.jpg,**/*.svg,.codespell-whitelist,vendor,_site,_config.yml,style.css eipw-validator: - name: EIP Walidator + name: EIP Validator runs-on: ubuntu-latest steps: diff --git a/README.md b/README.md index 7463a87d011277..3e6ec638ec2adb 100644 --- a/README.md +++ b/README.md @@ -85,3 +85,18 @@ eipw --config ./config/eipw.toml 2. Preview your local Jekyll site in your web browser at `http://localhost:4000`. More information on Jekyll and GitHub Pages [here](https://docs.github.com/en/enterprise/2.14/user/articles/setting-up-your-github-pages-site-locally-with-jekyll). + +## Writing Effective Technical Documentation + +Effective technical documentation is crucial for the success of any project. Here are some key points to consider when writing technical documentation: + +* **Clarity and simplicity**: Ensure that the documentation is clear and easy to understand. Use simple language and avoid jargon. 📝 +* **Structure and organization**: Organize the documentation in a logical manner. Use headings, subheadings, and bullet points to break down the content into manageable sections. 📚 +* **Consistency**: Maintain consistency in terminology, formatting, and style throughout the documentation. This helps in making the document more readable and professional. 🔄 +* **Accuracy**: Ensure that the information provided is accurate and up-to-date. Regularly review and update the documentation to reflect any changes in the project. ✅ +* **Examples and visuals**: Use examples, diagrams, and screenshots to illustrate complex concepts. This helps in making the documentation more engaging and easier to understand. 🖼️ +* **User-focused**: Keep the target audience in mind while writing the documentation. Ensure that the content is relevant and useful for the intended users. 👥 +* **Searchability**: Make the documentation easily searchable by including a table of contents, index, and keywords. This helps users quickly find the information they need. 🔍 +* **Feedback and improvement**: Encourage users to provide feedback on the documentation. Use this feedback to continuously improve the quality and usefulness of the documentation. 📈 + +By following these guidelines, you can create effective technical documentation that is clear, accurate, and user-friendly. diff --git a/eip-template.md b/eip-template.md index ffdde950ce130a..9bd40fd22f37f6 100644 --- a/eip-template.md +++ b/eip-template.md @@ -115,6 +115,30 @@ No backward compatibility issues found. Needs discussion. +## Examples and Visuals + +### Example 1: Simple Smart Contract + +```solidity +pragma solidity ^0.8.0; + +contract SimpleStorage { + uint256 public storedData; + + function set(uint256 x) public { + storedData = x; + } + + function get() public view returns (uint256) { + return storedData; + } +} +``` + +### Example 2: Visual Representation of a Transaction + +![Transaction Flow](../assets/eip-template/transaction-flow.png) + ## Copyright Copyright and related rights waived via [CC0](../LICENSE.md). diff --git a/index.html b/index.html index 5e7910d7913fbb..add885692ab7e8 100644 --- a/index.html +++ b/index.html @@ -14,10 +14,17 @@

EIPs

Ethereum Improvement Proposals (EIPs) describe standards for the Ethereum platform, including core protocol specifications, client APIs, and contract standards. Network upgrades are discussed separately in the Ethereum Project Management repository.

-

Contributing

+

Table of Contents

+ + +

Contributing

First review EIP-1. Then clone the repository and add your EIP to it. There is a template EIP here. Then submit a Pull Request to Ethereum's EIPs repository.

-

EIP status terms

+

EIP Status Terms

-

EIP Types

+

EIP Types

EIPs are separated into a number of types, and each has its own list of EIPs.

From e787ede71624908c107493a0412f81f7b61a9e85 Mon Sep 17 00:00:00 2001 From: Dustin4444 <126348160+Dustin4444@users.noreply.github.com> Date: Thu, 13 Mar 2025 06:49:08 -0400 Subject: [PATCH 2/3] --- .vscode/launch.json | 65 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 .vscode/launch.json diff --git a/.vscode/launch.json b/.vscode/launch.json new file mode 100644 index 00000000000000..72a8d140263454 --- /dev/null +++ b/.vscode/launch.json @@ -0,0 +1,65 @@ +{ + // Use IntelliSense to learn about possible attributes. + // Hover to view descriptions of existing attributes. + // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387 + "version": "0.2.0", + "configurations": [ + { + "command": "npm start", + "name": "Run npm start", + "request": "launch", + "type": "node-terminal" + }, + { + "name": "Launch Chrome", + "request": "launch", + "type": "chrome", + "url": "http://localhost:8080", + "webRoot": "${workspaceFolder}" + }, + + + { + "name": "Attach to Edge", + "port": 9222, + "request": "attach", + "type": "msedge", + "webRoot": "${workspaceFolder}" + }, + + + + { + "name": "Launch Program", + "program": "${workspaceFolder}/app.js", + "request": "launch", + "skipFiles": [ + "/**" + ], + "type": "node" + }, + { + "name": "Launch Program", + "program": "${workspaceFolder}/app.js", + "request": "launch", + "skipFiles": [ + "/**" + ], + "type": "node" + }, + { + "name": "Launch Chrome", + "request": "launch", + "type": "chrome", + "url": "http://localhost:8080", + "webRoot": "${workspaceFolder}" + }, + { + "type": "chrome", + "request": "launch", + "name": "Launch Chrome against localhost", + "url": "http://localhost:8080", + "webRoot": "${workspaceFolder}" + } + ] +} \ No newline at end of file From 306ad2c20f37155770a53b3e57078cb7f0b8e738 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Sun, 1 Mar 2026 22:14:29 +0000 Subject: [PATCH 3/3] Bump webrick from 1.8.1 to 1.8.2 Bumps [webrick](https://github.com/ruby/webrick) from 1.8.1 to 1.8.2. - [Release notes](https://github.com/ruby/webrick/releases) - [Commits](https://github.com/ruby/webrick/compare/v1.8.1...v1.8.2) --- updated-dependencies: - dependency-name: webrick dependency-version: 1.8.2 dependency-type: direct:production ... Signed-off-by: dependabot[bot] --- Gemfile.lock | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Gemfile.lock b/Gemfile.lock index 21a6074d83a08a..823f9b548f984f 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -285,7 +285,7 @@ GEM unf_ext unf_ext (0.0.8.2) unicode-display_width (1.8.0) - webrick (1.8.1) + webrick (1.8.2) yell (2.2.2) zeitwerk (2.6.7)