Add guide for contributing without a local environment #16764
Conversation
This PR adds an internal documentation page under docs/ that explains how to contribute to ethereum.org using only the GitHub web UI, without setting up a local environment. The guide summarizes when this workflow is appropriate, its limitations, and step-by-step instructions for editing or creating Markdown files directly on GitHub.
JonesRoy3
requested review from
corwintines,
minimalsm,
pettinarip and
wackerow
as code owners
✅ Deploy Preview for ethereumorg ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
wackerow
left a comment
wackerow
left a comment
There was a problem hiding this comment.
Looks good overall, thanks @JonesRoy3... just a few requests left below =)
Worth also considering how to surface this for users at this level so they can find this content
| 4. Scroll down to the **Commit changes** section: | ||
| - Write a short, descriptive commit message (e.g. `Fix typo in nodes and clients docs`). | ||
| - Optionally add a longer description explaining what you changed and why. | ||
| 5. Choose **“Commit directly to this branch”** (or create a new branch if you are working from your fork). |
There was a problem hiding this comment.
Would update to recommend a new branch with a simple name
| 6. Commit to your feature branch. | ||
| 7. Open a pull request to the upstream `dev` branch. | ||
|
|
||
| For content that appears on ethereum.org (not just internal docs), we usually keep Markdown files under `public/content/` and follow the structure explained in `docs/best-practices.md`. This document is meant to complement that guide, not replace it. |
There was a problem hiding this comment.
Markdown content is always in this folder. Would update to account for this, since JSON strings and TypeScript files are not recommended for this approach
| 1. Navigate to the folder where the file should live (e.g. `docs/`). | ||
| 2. Click **Add file → Create new file**. | ||
| 3. Enter a file name, such as `docs/my-new-guide.md` or `my-new-guide.md` if you are already inside the `docs/` folder. | ||
| 4. Paste your Markdown content into the editor. |
There was a problem hiding this comment.
Probably worth noting that front matter is needed for all markdown content files... it can get nuanced, so probably best to suggest looking at other files as examples
| - Prefer **small, focused PRs** that do one thing well. | ||
| - Double-check that you didn't accidentally edit unrelated lines when using the web editor. | ||
| - Use the **Preview** tab in the GitHub editor to verify Markdown formatting. | ||
| - If you are unsure whether a change is appropriate, open an issue first and ask for feedback. |
There was a problem hiding this comment.
Especially for new pages, an issue should be opened ahead of time
| - You cannot run automated tests before pushing changes. | ||
| - Large refactors are harder to review and reason about. | ||
|
|
||
| For frequent contributors or more complex work, we recommend switching to a full local development environment using `pnpm`, as documented in the main repository README. |
There was a problem hiding this comment.
Would scrape "using pnpm" comment, and turn README into a link
|
Overall not against this, but its a burried file that is unlikely to get seen so this seems a bit unnecessary IMO. Most of this can be looked up about github since its specific to github. Won't veto it completely, but changes @wackerow had should be addressed first. |
3 participants
This PR adds an internal documentation page under docs/ that explains how to contribute to ethereum.org using only the GitHub web UI, without setting up a local environment. The guide summarizes when this workflow is appropriate, its limitations, and step-by-step instructions for editing or creating Markdown files directly on GitHub.