diff --git a/README.md b/README.md index d1bffd614f3..a716796d04d 100644 --- a/README.md +++ b/README.md @@ -10,151 +10,25 @@

πŸ‘‹ Welcome to ethereum.org!

-This is the repo for the [ethereum.org](https://ethereum.org) website, a resource for the Ethereum community. The site's purpose is to _β€œBe the best portal to Ethereum for our growing global community"_ - read more about what this means [here](https://ethereum.org/en/about/). +This is the project repository for the [ethereum.org](https://ethereum.org) website, a resource for the Ethereum community. The site's purpose is to _β€œBe the best portal to Ethereum for our growing global community"_ - read more about what this means here. [ethereum.org](https://ethereum.org) is being improved and changed over time through the contributions of community members who submit content, code, design, help review give feedback, test, or volunteer their time to manage its evolution. -[ethereum.org](https://ethereum.org) is being improved and changed over time through the contributions of community members who submit content, give feedback, or volunteer their time to manage its evolution. If you’re interested in helping to improve [ethereum.org](https://ethereum.org), find out [how to contribute](https://ethereum.org/en/contributing/). - -## Looking for the Ethereum blockchain's code? - -If you're looking for the Ethereum blockchain itself, there is no single repo. Instead, Ethereum has multiple implementations of the protocol written in different programming languages for security and diversity. [Check out the different implementations](https://ethereum.org/en/developers/docs/nodes-and-clients/#execution-clients) - -
- -## Table of contents - -- [How to contribute](#how-to-contribute) -- [Translation Program](docs/translation-program.md) -- [The ethereum.org website stack](docs/stack.md) -- [Website conventions / best practices](docs/best-practices.md) - -## How to contribute - -This project follows the [all-contributors](https://allcontributors.org/docs/en/overview) specification. Contributions of any kind are welcome! - -### 1. Submit an issue - -- Create a [new issue](https://github.com/ethereum/ethereum-org-website/issues/new/choose). -- Comment on the issue (if you'd like to be assigned to it) - that way [our team can assign the issue to you](https://github.blog/2019-06-25-assign-issues-to-issue-commenters/). - -More information on the issue creation process, and expectations around creating issues can be [found here](docs/github-issue-triage-process.md). - -### 2. Fork the repository (repo) - -- If you're not sure, here's how to [fork the repo](https://help.github.com/en/articles/fork-a-repo). - -### 3. Set up your local environment (optional) - -If you're ready to contribute and create your PR, it will help to set up a local environment so you can see your changes. - -1. [Set up your development environment](https://www.gatsbyjs.com/docs/tutorial/part-zero/) - -2. Clone your fork - -If this is your first time forking our repo, this is all you need to do for this step: - -```sh -git clone git@github.com:[your_github_handle]/ethereum-org-website.git && cd ethereum-org-website -``` - -If you've already forked the repo, you'll want to ensure your fork is configured and that it's up to date. This will save you the headache of potential merge conflicts. - -To [configure your fork](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/configuring-a-remote-for-a-fork): - -```sh -git remote add upstream https://github.com/ethereum/ethereum-org-website.git -``` - -To [sync your fork with the latest changes](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/syncing-a-fork): - -```sh -git checkout dev -git fetch upstream -git merge upstream/dev -``` - -3. Install dependencies - -We recommend using a node manager to use multiple node versions in your system. We use [Volta](https://volta.sh/). In case you don't use a manager or you use `nvm`, you can check the currently supported versions under the `"volta"` section on our `package.json` file. - -```sh -yarn -``` - -### 4. Make awesome changes! - -1. Create new branch for your changes - -```sh -git checkout -b new_branch_name -``` - -2. Start developing! - -```sh -yarn dev -``` - -- Open this directory in your favorite text editor / IDE, and see your changes live by visiting `localhost:3000` from your browser -- Pro Tip: - - Explore scripts within `package.json` for more build options - - Get **faster** local builds by building only one language. E.g. in your `.env` file, set `BUILD_LOCALES=en` to build the content only in English - -By default the script will build all the languages (complete list in `data/translations.json`) and will ignore the `/docs` and `/tutorials` folders. To control this behavior you can play with the `BUILD_LOCALES` and `IGNORE_CONTENT` env variables. Check out `.env.example` to read more about them. - -3. Commit and prepare for pull request (PR). In your PR commit message, reference the issue it resolves (see [how to link a commit message to an issue using a keyword](https://docs.github.com/en/free-pro-team@latest/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword)). - -```sh -git commit -m "brief description of changes [Fixes #1234]" -``` - -4. Push to your GitHub account - -```sh -git push -``` - -### 5. Local development with lambda functions - -There may be times where you develop features that make external API requests to other services. For these we write lambda functions to obfuscate API keys. - -To use an existing function locally you don't need to do anything. Just check that you have set the necessary ENV variables in the `.env` file. - -To create a new function, you will need to create two files: - -- One in `src/lambda` where the logic will live. These are the ones that will be deployed to Netlify. These functions follow [this format](https://docs.netlify.com/functions/build-with-javascript/#synchronous-function-format). -- One in `src/api` that will be just a wrapper around the previous one in order to be compatible with Gatsby functions. More on the [Gatsby docs](https://www.gatsbyjs.com/docs/reference/functions/getting-started/) for the format they follow. - -Typically, you will develop and test functions in the Gatsby context, by running `yarn start`. - -In case you want to test them as if you were in a Netlify env, you can install the [Netlify CLI](https://docs.netlify.com/cli/get-started/) and run `netlify dev --framework=gatsby`. - -### 6. Submit your PR - -- After your changes are committed to your GitHub fork, submit a pull request (PR) to the `dev` branch of the `ethereum/ethereum-org-website` repo -- In your PR description, reference the issue it resolves (see [linking a pull request to an issue using a keyword](https://docs.github.com/en/free-pro-team@latest/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword)) - - ex. `Updates out of date content [Fixes #1234]` -- Gatsby Cloud (our hosting service for build previews) deploys all PRs to a publicly accessible preview URL, e.g.: - ![Gatsby Cloud deploy preview](./GC-preview-deploy.png) -- _Confirm your GC preview deploy looks & functions as expected_ -- Why not say hi and draw attention to your PR in [our discord server](https://discord.gg/ethereum-org)? - -### 7. Wait for review +### Join our Discord server -- The website team reviews every PR -- See [how decisions are made on content changes](https://ethereum.org/en/contributing/#how-decisions-about-the-site-are-made) -- Acceptable PRs will be approved & merged into the `dev` branch +We have a space to discuss all things ethereum.org – share your ideas or just say hi over [on Discord](https://discord.gg/ethereum-org). -Learn more about how we review pull requests [here](docs/review-process.md). +## How to contribute to ethereum.org -### 8. Release +There are a number of ways for you to contribute to ethereum.org. Click on the contribution type you are interested in for more information. -- `master` is continually synced to Netlify and will automatically deploy new commits to ethereum.org -- Learn more about how we deploy the site [here](docs/deploy-process.md) -- You can [view the history of releases](https://github.com/ethereum/ethereum-org-website/releases), which include PR highlights +- [Code contributions](https://ethereum.org/en/contributing/code) +- [Content contributions](https://ethereum.org/en/contributing/content) +- [Design contributions](https://ethereum.org/en/contributing/design/#design-contributions) +- [Translation program contributions](https://ethereum.org/en/contributing/translation-program/#translation-program) +- [QA testing contributions](https://ethereum.org/en/contributing/testing) -
+## Looking for the Ethereum client code? -![POAP Logo](public/poap-logo.svg) +If you're looking for the Ethereum blockchain itself, there is no single repo. Instead, Ethereum has multiple implementations of the protocol written in different programming languages for security and diversity. [Check out the different implementations](https://ethereum.org/en/developers/docs/nodes-and-clients/#execution-clients) ## Claim your POAP! @@ -162,24 +36,15 @@ Learn more about how we review pull requests [here](docs/review-process.md). > The Proof of Attendance Protocol is a dapp that distributes badges in the form of ERC-721 tokens to prove you participated in an event. [More on POAPs](https://www.poap.xyz/). -### ethereum.org 2022 Contributor POAP +### ethereum.org 2023 Contributor POAP -- If you have committed any changes in 2022 so far that were merged into our repo, you have a POAP waiting! -- This includes our dedicated translators on Crowdin +If you have committed any changes in 2023 so far that were merged into our repo, you have a [GitPOAP](https://www.gitpoap.io/) waiting! Check out your pull request for a claim message. - [![Discord](https://img.shields.io/discord/714888181740339261?color=1C1CE1&label=Claim%20Your%20POAP!%20%7C%20Discord%20%F0%9F%91%8B%20&style=flat)](https://discord.gg/ethereum-org) - -- πŸ‘† To claim your Contributor POAP, join our Discord server and paste a link to your contribution in the `#πŸ₯‡ | poaps` [channel](https://discord.com/channels/714888181740339261/804005643211898911) +If you have contributed translations to the translation program: +- Join our Discord server and paste a link to your Crowdin account in the `#πŸ₯‡ | poaps` [channel](https://discord.com/channels/714888181740339261/804005643211898911). Crowdin contributors will be verified directly through Crowdin by our team. - A member of our team will verify the request and DM you with a personalized link to claim your own freshly minted POAP collectible! -- To help with verification we request GitHub contributors connect their GitHub account with their Discord account (Discord > Settings > Connections > GitHub). Crowdin contributors will be verified directly through Crowdin by our team. - -### GitPOAP - -- If you've made at least one contribution and that gets merged into ethereum.org, GitPOAP will also auto recognize it and let you mint a unique contributor POAP for the specific year. - [More on GitPOAP](https://www.gitpoap.io). - If you haven't contributed yet and would like to earn a POAP to show your loyalty to the Ethereum space, head over to the [issues](https://github.com/ethereum/ethereum-org-website/issues/) tab to get started!
@@ -1643,7 +1508,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d Francesco Ciulla
Francesco Ciulla
πŸ–‹ - blazingrome
blazingrome
πŸ–‹ + blazingrome
blazingrome
πŸ–‹ Etan Kissling
Etan Kissling
πŸ–‹ kritik sah
kritik sah
πŸ› Fuliggine
Fuliggine
πŸ–‹ @@ -1733,9 +1598,3 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d - -This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome! - -### Join our Discord server - -We have a space to discuss all things ethereum.org – share your ideas or just say hi over [on Discord](https://discord.gg/ethereum-org). diff --git a/docs/translation-program.md b/docs/translation-program.md deleted file mode 100644 index 9fb2f98a5b7..00000000000 --- a/docs/translation-program.md +++ /dev/null @@ -1,7 +0,0 @@ -# Translation Program - -_The Translation Program is an initiative to translate ethereum.org into different languages and make the website accessible to people from all over the world._ - -If you are looking to get involved as a translator, you can [join our project in Crowdin](https://crowdin.com/project/ethereum-org/) and start translating the website to your language immediately. - -To get more information about the program, learn how to use Crowdin, check on the progress or find some useful tools for translators, please visit the [Translation Program page](https://ethereum.org/en/contributing/translation-program/). diff --git a/public/content/contributing/index.md b/public/content/contributing/index.md index 4b24e8161ce..071d5ed7460 100644 --- a/public/content/contributing/index.md +++ b/public/content/contributing/index.md @@ -6,21 +6,37 @@ lang: en # Contributing to ethereum.org πŸ¦„ {#contributing-to-ethereumorg} -The ethereum.org website, like Ethereum more broadly, is an open-source project. So if you want to help improve [our portal to Ethereum](/about/), here's how you can help out. +ethereum.org's purpose is to _β€œBe the best portal to Ethereum for our growing global community"_ - read more about what this means [here](/about/#our-mission). ethereum.org is being improved and changed over time through the contributions of community members who submit content, code, design, help review give feedback, test, or volunteer their time to manage its evolution. - - Claim your POAP token! If you contributed to ethereum.org in 2022, there's a unique POAP waiting for you.{" "} - More on POAPs - +Before contributing, make sure you're familiar with: + +- the evolving [vision of ethereum.org](/about/) +- our [design principles](/contributing/design-principles/) +- our [style guide](/contributing/style-guide/) +- our [code of conduct](/community/code-of-conduct) ## Ways to contribute {#ways-to-contribute} -- [Work on an open issue](https://github.com/ethereum/ethereum-org-website/issues) - _– Work we've identified that needs doing_ -- [Join the translation program](/contributing/translation-program/) - _– Help us bring ethereum.org to new languages_ -- [Help design the website](/contributing/design/) - _– Designers of all levels can contribute to improve the website_ +### Contribution types {#contribution-types} + +There are a number of ways for you to contribute to ethereum.org. Click on the contribution type you are interested in for more information. + +- [Code contributions](/contributing/code/) _- Help us with code contributions for ethereum.org_ +- [Content contributions](/contributing/content/) _- Help us add/update content for ethereum.org_ +- [Design contributions](/contributing/design/#design-contributions) _– Designers of all levels can contribute to improve the website_ +- [Translation program contributions](/contributing/translation-program/#translation-program) _– Help us bring ethereum.org to new languages_ +- [QA testing contributions](/contributing/testing/) _- Help us test release candidates for ethereum.org_ + +### Suggest improvements {#suggest-improvements} + +- [Request a feature](https://github.com/ethereum/ethereum-org-website/issues/new?assignees=&labels=Type%3A+Feature&template=feature_request.yaml&title=) + _– Let us know about any ideas you have for a new feature or design_ +- [Add a glossary term](/contributing/adding-glossary-terms) + _– Help us continue to expand the Ethereum [glossary](/glossary/)_ +- [Quizzes](/contributing/quizzes/) _- Add, update, and delete quiz question banks for a relevant page_ + +### Add resources or projects {#add-resources-or-projects} + - [Add community resources](/contributing/content-resources/) _– Add a helpful article or resource to a relevant page_ - [Add a product](/contributing/adding-products/) @@ -29,14 +45,6 @@ The ethereum.org website, like Ethereum more broadly, is an open-source project. _– Add a developer tool to a relevant page_ - [Add an exchange](/contributing/adding-exchanges/) _– Add an exchange to our [exchange finder](/get-eth/#country-picker)_ -- [Improve our research](https://www.notion.so/efdn/Ethereum-org-User-Persona-Memo-b44dc1e89152457a87ba872b0dfa366c) - _– Let us know your feedback on our research or contribute your own_ -- [Request a feature](https://github.com/ethereum/ethereum-org-website/issues/new?assignees=&labels=Type%3A+Feature&template=feature_request.yaml&title=) - _– Let us know about any ideas you have for a new feature or design_ -- [Add a glossary term](/contributing/adding-glossary-terms) - _– Help us continue to expand the Ethereum [glossary](/glossary/)_ -- [Create/edit content](/contributing/#how-to-update-content) - _– Suggest new pages or make tweaks to what's here already_ - [Add a layer 2](/contributing/adding-layer-2s/) _– Add a layer 2 to a relevant page_ - [Add a staking product or service](/contributing/adding-staking-products/) @@ -45,29 +53,19 @@ The ethereum.org website, like Ethereum more broadly, is an open-source project. _– Add a wallet for the [find wallets page](/wallets/find-wallet/)_ - [Suggest a project for our DeSci page](/contributing/adding-desci-projects/) _- Add a project built on Ethereum that contributes to decentralized science_ -- [Quizzes](/contributing/quizzes/) _- Add, update, and delete quiz question banks for a relevant page_ - [Suggest a design resource](/contributing/design/adding-design-resources/) _- Add, update, and delete helpful design resources_ _Any questions?_ πŸ€” Reach out on our [Discord server](https://discord.gg/ethereum-org) ## How to work on ethereum.org {#how-to-update-content} -Whether you're adding to the site, creating content or working on open issues, you'll need a [GitHub](https://github.com) account. +Whether you're adding to the site, creating content or working on open issues, you'll need a [GitHub](https://github.com) account. If you are working on design related work, you'll need a [Figma](https://figma.com) account. -All updates are made via the GitHub PR process. This means you create a local copy of the website, make your changes and request to merge your changes. If you've never done this before, follow the instructions at the bottom of our [GitHub repository](https://github.com/ethereum/ethereum-org-website). - -You don't need permission to work on anything, but it's always best to let us know what you're planning to do. You can do this by: +You don't need permission to work on anything, but it's always best to let us know what you're planning to do to avoid wasting time. You can do this by: - Commenting on an issue or PR in [GitHub](https://github.com/ethereum/ethereum-org-website) - Messaging on our [Discord server](https://discord.gg/ethereum-org) -Before contributing, make sure you're familiar with: - -- the evolving [vision of ethereum.org](/about/) -- our [design principles](/contributing/design-principles/) -- our [style guide](/contributing/style-guide/) -- our [code of conduct](/community/code-of-conduct) - ## How decisions about the site are made {#how-decisions-about-the-site-are-made} Decisions about individual PRs, design evolution and major upgrades are made by a team from across the Ethereum ecosystem. This team includes project managers, developers, designers, marketing and communications, and subject matter experts. Community input informs every decision: so please raise questions in issues, submit PRs, or contact the team: @@ -84,20 +82,16 @@ Only use your original work or content that you have permission to use when cont We have low barrier to entry issues on our GitHub repository specifically designed for developers who are new to open-source labelled [good first issue](https://github.com/ethereum/ethereum-org-website/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22). -## Claim your contributor POAP {#poap} +## ethereum.org 2023 Contributor POAP {#ethereumorg-2023-contributor-poap} -If your contribution gets merged into ethereum.org, we'll mint you a unique contributors POAP. A Proof of Attendance Protocol (POAP) token is on-chain proof that you helped make the ecosystem a little more awesome. +If you have committed any changes in 2023 so far that were merged into our repo, you have a [GitPOAP](https://www.gitpoap.io/) waiting! Check out your pull request for a claim message. -[More on POAPs](https://www.poap.xyz/) - -### How to claim {#how-to-claim} +If you have contributed translations to the translation program: -1. Join our [Discord server](https://discord.gg/ethereum-org). -2. Paste a link to your contribution in the `#πŸ₯‡ | poaps` [channel](https://discord.com/channels/714888181740339261/804005643211898911). -3. Wait for a member of our team to send you a link to your POAP. -4. Claim your POAP! +- Join our Discord server and paste a link to your Crowdin account in the `#πŸ₯‡ | poaps` [channel](https://discord.com/channels/714888181740339261/804005643211898911). Crowdin contributors will be verified directly through Crowdin by our team. +- A member of our team will verify the request and DM you with a personalized link to claim your own freshly minted POAP collectible! -You should only use self-custody wallets to claim POAPs. Do not use exchange accounts or other accounts you do not hold the private keys to, as these will not allow you to access and manage your POAPs. +If you haven't contributed yet and would like to earn a POAP to show your loyalty to the Ethereum space, head over to the [issues](https://github.com/ethereum/ethereum-org-website/issues/) tab to get started! ## Claim your GitPOAP {#claim-gitpoap} diff --git a/src/content/contributing/code/GC-preview-deploy.png b/src/content/contributing/code/GC-preview-deploy.png new file mode 100644 index 00000000000..626464974ad Binary files /dev/null and b/src/content/contributing/code/GC-preview-deploy.png differ diff --git a/src/content/contributing/code/index.md b/src/content/contributing/code/index.md new file mode 100644 index 00000000000..247d41dd206 --- /dev/null +++ b/src/content/contributing/code/index.md @@ -0,0 +1,135 @@ +--- +title: Code contributions +description: Code contribution to ethereum.org +lang: en +--- + +### 1. Submit an issue {#submit-an-issue} + +- Create a [new issue](https://github.com/ethereum/ethereum-org-website/issues/new/choose). +- Comment on the issue (if you'd like to be assigned to it) - that way [our team can assign the issue to you](https://github.blog/2019-06-25-assign-issues-to-issue-commenters/). + +More information on the issue creation process, and expectations around creating issues can be [found here](https://github.com/ethereum/ethereum-org-website/blob/dev/docs/github-issue-triage-process.md). + +### 2. Fork the repository (repo) {#fork-the-repository} + +- If you're not sure, here's how to [fork the repo](https://help.github.com/en/articles/fork-a-repo). + +### 3. Set up your local environment (optional) {#set-up-your-local-environment} + +If you're ready to contribute and create your PR, it will help to set up a local environment so you can see your changes. + +1. [Set up your development environment](https://www.gatsbyjs.com/docs/tutorial/part-zero/) + +2. Clone your fork + +If this is your first time forking our repo, this is all you need to do for this step: + +```sh +git clone git@github.com:[your_github_handle]/ethereum-org-website.git && cd ethereum-org-website +``` + +If you've already forked the repo, you'll want to ensure your fork is configured and that it's up to date. This will save you the headache of potential merge conflicts. + +To [configure your fork](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/configuring-a-remote-for-a-fork): + +```sh +git remote add upstream https://github.com/ethereum/ethereum-org-website.git +``` + +To [sync your fork with the latest changes](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/syncing-a-fork): + +```sh +git checkout dev +git fetch upstream +git merge upstream/dev +``` + +3. Install dependencies + +We recommend using a node manager to use multiple node versions in your system. We use [Volta](https://volta.sh/). In case you don't use a manager or you use `nvm`, you can check the currently supported versions under the `"volta"` section on our `package.json` file. + +```sh +yarn +``` + +### 4. Make awesome changes! {#make-awesome-changes} + +1. Create new branch for your changes off of your local `dev` branch + +```sh +git checkout -b new_branch_name +``` + +2. Start developing! + +Install dependencies and clear cache + +```sh +rm -rf node_modules && yarn install && npx gatsby clean +``` + +Start the project + +```sh +yarn start +``` + +- Open this directory in your favorite text editor / IDE, and see your changes live by visiting `localhost:8000` from your browser +- Pro Tip: + - Explore scripts within [`package.json`](https://github.com/ethereum/ethereum-org-website/blob/dev/package.json) for more build options + - Get **faster** local builds by building only one language. E.g. in your [`.env`](https://github.com/ethereum/ethereum-org-website/blob/dev/.env.example) file, set `GATSBY_BUILD_LANGS=en` to build the content only in English + +By default the script will build all the languages (complete list in [`src/utils/languages.ts`](https://github.com/ethereum/ethereum-org-website/blob/dev/src/utils/languages.ts)) and will ignore the `/docs` and `/tutorials` folders. To control this behavior you can play with the `GATSBY_BUILD_LANGS` and `IGNORE_CONTENT` env variables. Check out `.env.example` to read more about them. + +3. Commit and prepare for pull request (PR). In your PR commit message, reference the issue it resolves (see [how to link a commit message to an issue using a keyword](https://docs.github.com/en/free-pro-team@latest/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword)). + +```sh +git commit -m "brief description of changes [Fixes #1234]" +``` + +4. Push to your GitHub account + +```sh +git push +``` + +### 5. Local development with lambda functions {#local-development-with-lambda-functions} + +There may be times where you develop features that make external API requests to other services. For these we write lambda functions to obfuscate API keys. + +To use an existing function locally you don't need to do anything. Just check that you have set the necessary ENV variables in the `.env` file. + +To create a new function, you will need to create two files: + +- One in [`src/lambda`](https://github.com/ethereum/ethereum-org-website/tree/dev/src/lambda) where the logic will live. These are the ones that will be deployed to Netlify. These functions follow [this format](https://docs.netlify.com/functions/build-with-javascript/#synchronous-function-format). +- One in [`src/api`](https://github.com/ethereum/ethereum-org-website/tree/dev/src/api) that will be just a wrapper around the previous one in order to be compatible with Gatsby functions. More on the [Gatbsy docs](https://www.gatsbyjs.com/docs/reference/functions/getting-started/) for the format they follow. + +Typically, you will develop and test functions in the Gatsby context, by running `yarn start`. + +In case you want to test them as if you were in a Netlify env, you can install the [Netlify CLI](https://docs.netlify.com/cli/get-started/) and run `netlify dev --framework=gatsby`. + +### 6. Submit your PR {#submit-your-pr} + +- After your changes are committed to your GitHub fork, submit a pull request (PR) to the `dev` branch of the `ethereum/ethereum-org-website` repo +- In your PR description, reference the issue it resolves (see [linking a pull request to an issue using a keyword](https://docs.github.com/en/free-pro-team@latest/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword)) + - ex. `Updates out of date content [Fixes #1234]` +- Gatsby Cloud (our hosting service for build previews) deploys all PRs to a publicly accessible preview URL, e.g.: + ![Gatsby Cloud deploy preview](./GC-preview-deploy.png) +- _Confirm your GC preview deploy looks & functions as expected_ +- Why not say hi and draw attention to your PR in [our discord server](https://discord.gg/ethereum-org)? + +### 7. Wait for review {#wait-for-review} + +- The website team reviews every PR +- See [how decisions are made on content changes](https://ethereum.org/en/contributing/#how-decisions-about-the-site-are-made) +- Acceptable PRs will be approved & merged into the `dev` branch +- Your first accepted PR for the year gets you a POAP. [More information on our POAP](https://ethereum.org/en/contributing/#claim-gitpoap). + +Learn more about how we review pull requests [here](docs/review-process.md). + +### 8. Release {#release} + +- `master` is continually synced to Netlify and will automatically deploy new commits to ethereum.org +- Learn more about how we deploy the site [here](docs/deploy-process.md) +- You can [view the history of releases](https://github.com/ethereum/ethereum-org-website/releases), which include PR highlights diff --git a/src/content/contributing/content/first_image_create_markdown.png b/src/content/contributing/content/first_image_create_markdown.png new file mode 100644 index 00000000000..a6000242995 Binary files /dev/null and b/src/content/contributing/content/first_image_create_markdown.png differ diff --git a/src/content/contributing/content/first_image_edit_markdown.png b/src/content/contributing/content/first_image_edit_markdown.png new file mode 100644 index 00000000000..d650bedcf9b Binary files /dev/null and b/src/content/contributing/content/first_image_edit_markdown.png differ diff --git a/src/content/contributing/content/index.md b/src/content/contributing/content/index.md new file mode 100644 index 00000000000..d76ee1c645e --- /dev/null +++ b/src/content/contributing/content/index.md @@ -0,0 +1,128 @@ +--- +title: Content contributions +description: Content contribution to ethereum.org +lang: en +--- + +# Content contributions to ethereum.org {#content-contributions} + +Ethereum.org is an education portal for Ethereum, and that starts with the content being contributed by the community. We encourage contributions for new content, and updating existing content to keep it up to date. + +Before contributing to content, make sure you are familiar with our [style guide](/contributing/style-guide/). + +You're first content contribution of the year earns you a POAP. [More information on our POAP](https://ethereum.org/en/contributing/#claim-gitpoap). + +## Markdown content in `/src/content` {#markdown-content} + +Most of the content on ethereum.org is written in markdown. A cheat sheet on markdown syntax can be found [here](https://www.markdownguide.org/cheat-sheet). + +These markdown files are found in [`/src/content` of the project repository](https://github.com/ethereum/ethereum-org-website/tree/dev/src/content). Each folder has an `index.md` for the content and corresponds to a page on ethereum.org. For example, this page [https://ethereum.org/contributing/content](/contributing/content) can be found in the [`/src/content/contributing/content/index.md`](https://github.com/ethereum/ethereum-org-website/tree/dev/src/content/contributing/content/index.md) file. + +#### A note on the developer docs {#a-note-on-the-developer-docs} + +Many pages on ethereum.org are in the developer docs section of the website. Like all the other pages described above, these are found in the content folder under `/src/content/developers/docs/{folder_for_page_you_are_looking_for}`. + +### How to edit a markdown page {#how-to-edit-a-markdown-page} + +#### In GitHub {#how-to-edit-a-markdown-page-in-github} + +Find the page you are looking to edit in [`/src/content/`](https://github.com/ethereum/ethereum-org-website/tree/dev/src/content) folder. The structure of the content folder maps to the url of ethereum.org. For this example, lets edit the about page. + +We can find the about page at [https://github.com/ethereum/ethereum-org-website/blob/dev/src/content/about/index.md](https://github.com/ethereum/ethereum-org-website/blob/dev/src/content/about/index.md) which will change the `/about` page ([https://ethereum.org/about](/about)). As you can see the mapping of where the content is corresponds to the URL of the website. + +![](./first_image_edit_markdown.png) + +Hit the edit button in the top left, and make any content changes for the page. After you have finished making your changes, you can select `Commit changes...` to commit your contribution. + +![](./second_image_edit_markdown.png) + +Make sure you you add an informative description, and branch name. + +![](third_image_edit_markdown.png) + +Once you have done this, make a pull request into the `dev` branch from your newly created branch and we will review it! + +#### Locally cloned repository {#how-to-edit-a-markdown-page-locally-cloned-repository} + +Find the page you are looking to edit in [`/src/content/`](https://github.com/ethereum/ethereum-org-website/tree/dev/src/content) folder. The structure of the content folder maps to the url of ethereum.org. For this example, lets edit the about page. More on code contributions and working with the repository can be found on our [code contributions](/contributing/code) page. + +Make a branch off of your forks `dev` branch. Make sure you have a descriptive branch name. + +We can find the about page in the [`/src/content/about/index.md`](https://github.com/ethereum/ethereum-org-website/blob/dev/src/content/about/index.md) file, which will change the `/about` page ([https://ethereum.org/about](/about)). As you can see, the mapping of where the content is corresponds to the URL of the website. + +Make changes to the [`/src/content/about/index.md`](https://github.com/ethereum/ethereum-org-website/blob/dev/src/content/about/index.md) file, and save. Then commit and push your changes up to your branch. Example terminal command: + +```sh +git add +git commit -m "" +git push origin +``` + +Lastly, make a pull request into the `dev` branch from your forks branch and we will review it. + +### How to create a markdown page {#how-to-create-a-markdown-page} + +#### In GitHub {#how-to-create-a-markdown-page-in-github} + +In the [`/src/content/`](https://github.com/ethereum/ethereum-org-website/tree/dev/src/content) folder, create a folder with the structure of the url. For example, [`/src/content/about/index.md`](https://github.com/ethereum/ethereum-org-website/blob/dev/src/content/about/index.md) maps to the `/about` ([https://ethereum.org/about](/about)) page on the website. + +Click on the `Add file` button in the top right, and select `Create new file` + +![](./first_image_create_markdown.png) + +Type the path out for the new page. Remember, the path in this folder maps to the URL. In this example, we will create /test, by typing `test/index.md` in the text area. After doing that, write your content in markdown. At the start of this page, make sure to include the necessary frontmatter text, description, and lang. + +![](./second_image_create_markdown.png) + +After you have written your content, click `Commit changes...` in the top right to commit your new page contribution. Make sure you you add an informative description, and branch name. + +![](./third_image_create_markdown.png) + +Once you have done this, make a pull request into the `dev` branch from your newly created branch and we will review it! + +#### Locally cloned repository {#how-to-create-a-markdown-page-locally-cloned-repository} + +In the [`/src/content/`](https://github.com/ethereum/ethereum-org-website/tree/dev/src/content) folder, create a folder with the structure of the url. For example, [`/src/content/about/index.md`(https://github.com/ethereum/ethereum-org-website/blob/dev/src/content/about/index.md) maps to the `/about` ([https://ethereum.org/about](/about)) page on the website. + +For the purpose of this example, create a folder for the `/test` page with an `index.md` file. This should create the structure `/src/content/test/index.md` Remember, the path in this structure maps to the URL. After doing that, write your content in markdown. At the start of the page, make sure to include the necessary frontmatter text, description, and lang. + +```markdown +--- +title: Content contributions +description: Content contribution to ethereum.org +lang: en +--- + +# Test header + +Test content +``` + +Commit your changes and push them up to your branch. + +```sh +git add +git commit -m "" +git push origin +``` + +Lastly, make a pull request into the `dev` branch from your fork and we will review it. + +### Custom header ID's for translations {#custom-header-ids} + +All markdown pages should include custom header IDs for each header. For example: + + +```markdown +## Here is a header {#here-is-a-header} + +Content... +``` + +The `{#here-is-a-header}` tag will be parsed into an `id` for this header, and is used for hash links to take a user directly to this section. For example: [https://ethereum.org/about#a-note-on-names](https://ethereum.org/about#a-note-on-names) will take a user directly to the `A note on names` section of the about page. + +This custom ID is intentionally _not translated_ during the translation process, allowing the link to work for any language, since the link ID will not change from language-to-language. + +If this is not included, a new ID will be generated for each language, breaking the portability of these links between languages. + +These ID's should be unique to the page. Typically a "kebab-cased" version of the header label itself is used, but this is not required, and should be changed for any recurring header labels (ie: multiple "Example" sub-sections should _not_ all be named `{#example}`). diff --git a/src/content/contributing/content/second_image_create_markdown.png b/src/content/contributing/content/second_image_create_markdown.png new file mode 100644 index 00000000000..229a8780708 Binary files /dev/null and b/src/content/contributing/content/second_image_create_markdown.png differ diff --git a/src/content/contributing/content/second_image_edit_markdown.png b/src/content/contributing/content/second_image_edit_markdown.png new file mode 100644 index 00000000000..2539e425e71 Binary files /dev/null and b/src/content/contributing/content/second_image_edit_markdown.png differ diff --git a/src/content/contributing/content/third_image_create_markdown.png b/src/content/contributing/content/third_image_create_markdown.png new file mode 100644 index 00000000000..fa35ec72fbb Binary files /dev/null and b/src/content/contributing/content/third_image_create_markdown.png differ diff --git a/src/content/contributing/content/third_image_edit_markdown.png b/src/content/contributing/content/third_image_edit_markdown.png new file mode 100644 index 00000000000..5bfc7548298 Binary files /dev/null and b/src/content/contributing/content/third_image_edit_markdown.png differ diff --git a/src/content/contributing/testing/index.md b/src/content/contributing/testing/index.md new file mode 100644 index 00000000000..69ef4c28530 --- /dev/null +++ b/src/content/contributing/testing/index.md @@ -0,0 +1,34 @@ +--- +title: Testing contributions +description: Testing contribution to ethereum.org +lang: en +--- + +# Testing contributions to ethereum.org {#testing-contributions} + +The QA testing contributions is an initiative to test release candidates for ethereum.org before they are deployed into production. Testing is a vital part in a products release cycle to catch bugs and regressions that may have been introduced before a release. + +If you'd like to get involved come say hi in our `πŸ‘Ύ ｜ website-code`. We meet bi-weekly in the `πŸŽ“ | office-hours-voice` channel in our [Discord](https://discord.gg/ethereum-org). Notes on our process: + +- **Every Tuesday** we create a release candidate that goes into the `staging` branch +- Infor about the release candidate is posted in the `πŸ‘Ύ ｜ website-code` channel in our [Discord](https://discord.gg/ethereum-org) +- Find the release notes for the release candidate on the [GitHub repositories releases page](https://github.com/ethereum/ethereum-org-website/releases) + - The release candidate will be tagged as a `pre-release` +- **On Thursday** the release candidate is published on production +- More info on the deploy process for ethereum.org can be found [here](https://github.com/ethereum/ethereum-org-website/blob/dev/docs/deploy-process.md) + +## How to get involved {#how-to-get-involved} + +There are a number of ways to get involved with testing. We are looking for any content, design, or user experience bugs or regressions that may have been introduced in the release candidate. + +### Content {#content} + +In every release there are content edits, and sometimes new pages being added to ethereum.org. One way to get involved for content contributions is reviewing new content and edits to make sure there is no wrong information, or grammar mistakes. + +### Design {#design} + +In some releases there will be changes to styles for components and pages on ethereum.org. As we roll out our [design system](/about/#design-system), we want to make sure there is no regression to designs and that we are maintaining this system. One way to get involved would be to test the release candidate and find any regressions that may have been introduced and report them. Another way to get involved is during testing, if you find other design issues or improvements, creating an issue on the repository advocating for these improvements. + +### User experience {#user-experience} + +One of our goals is to add more interactive elements to ethereum.org to supplement and improve content and learning for our users. With added interactivity comes a more complex codebase and increased chances for regressions in our user experience. One way to get involved for test release candidates is to test out these new pieces of functionality being added and provide any feedback on them and any issues or regressions found while testing them out.