From 1ad4433f8cee586a010e17921ed0929b4b5aef29 Mon Sep 17 00:00:00 2001 From: dave | d1onys1us <13951458+d1onys1us@users.noreply.github.com> Date: Wed, 4 Jan 2023 20:53:38 -0500 Subject: [PATCH] docs: improve documentation (#8556) --- CONTRIBUTING.md | 110 +++++------------- .../docs/alpha-1-testnet/configure-wallet.mdx | 2 +- .../docs/alpha-1-testnet/deploy-a-contract.md | 2 +- .../website/docs/alpha-1-testnet/get-help.md | 2 +- .../alpha-1-testnet/request-from-faucet.md | 12 +- .../docs/alpha-1-testnet/run-a-node.md | 6 +- .../docs/alpha-1-testnet/start-here.md | 4 +- .../docs/alpha-1-testnet/use-the-bridge.md | 2 +- 8 files changed, 47 insertions(+), 93 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c938c0781e5..dba1966d47d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,110 +1,62 @@ -# Contributing guide +# Taiko contributing guide -This contributing guide is divided into the following sections: +**Table of contents:** -1. [Make a contribution](#make-a-contribution) -2. [Claim a GitPOAP](#claim-a-gitpoap) -3. [Git standards](#git-standards) -4. [Documentation style guide](#documentation-style-guide) +- [Make a contribution](#make-a-contribution) +- [Claim a Taiko Contributor GitPOAP](#claim-a-taiko-contributor-gitpoap) +- [Coding standards](#coding-standards) +- [Documentation standards](#documentation-standards) # Make a contribution -We use [GitHub issues](https://github.com/taikoxyz/taiko-mono/issues) to track work. We use [GitHub discussions](https://github.com/taikoxyz/taiko-mono/discussions) to ask questions and talk about ideas. +Here are some ways you can contribute: -## Opening a new issue +- Open a new issue [here](https://github.com/taikoxyz/taiko-mono/issues). +- Work on an existing issue (check out the [good first issues list](https://github.com/taikoxyz/taiko-mono/labels/good%20first%20issue)). +- Ask questions and participate in [discussions](https://github.com/taikoxyz/taiko-mono/discussions). -If you are opening a new issue, try to be descriptive as possible. Also please check if an existing issue already exists for it already. +> Check out the [coding standards](#coding-standards) and [documentation standards](#documentation-standards) before you start working on a pull request. -## Working on an issue +# Claim a Taiko Contributor GitPOAP -If you are looking for a good issue to start with, look for issues tagged with [good first issue](https://github.com/taikoxyz/taiko-mono/labels/good%20first%20issue). Once you've found an issue to work on, you can assign it to yourself on GitHub and/or leave a comment that you're picking it up. Take a look at our [git standards](#git-standards). +A Taiko Contributor GitPOAP is rewarded to anyone that merges in a pull request to one of Taiko's GitHub repositories (for example: [2023 Taiko Contributor GitPOAP](https://www.gitpoap.io/gp/893)). -## Ask questions and start discussions +After your pull request is merged, a bot will automatically leave a comment with instructions to receive your GitPOAP. You only receive a Taiko Contributor GitPOAP for the first pull request you merge in a given year. -You can participate in questions and discussions under our [GitHub discussions](https://github.com/taikoxyz/taiko-mono/discussions). +# Coding standards -# Claim a GitPOAP +### Pull requests -We are rewarding community contributions with a GitPOAP. This guide explains the requirements to claim a GitPOAP. +Specify the scope of your change with a [conventional commit](https://www.conventionalcommits.org/en/v1.0.0/) in the PR title (for example, `feat(scope): description of feature`). This will be squashed and merged into the `main` branch. -## XXXX Taiko Contributor GitPOAP +### Source code comments -The XXXX Taiko Contributor GitPOAP is intended for anyone who makes a meaningful contribution to Taiko during the year XXXX. You can only earn this in the following ways: +Follow the [NatSpec format](https://docs.soliditylang.org/en/latest/natspec-format.html) for documenting smart contract source code. Please adhere to a few additional standards: -- Receive an accepted answer under [GitHub Discussions](https://github.com/taikoxyz/taiko-mono/discussions) -- Merge in a change to one of [our GitHub repos](https://github.com/taikoxyz) +- Choose `/** */` over `///` for multi-line NatSpec comments to save column space. +- Omit the usage of `@notice` and let the compiler automatically pick it up to save column space. + - For example: `/** @notice This is a notice */` becomes `/** This is a notice */`. -## How do I receive my GitPOAP? +# Documentation standards -There are two ways to receive a GitPOAP: +Use the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) as a base point of reference. -- If you merged in a pull request, the gitpoap-bot should have left you a comment to receive your GitPOAP like so: - ![](/assets/images/2022-12-14-09-30-37.png) -- If you made another contribution which fits the requirements of the GitPOAP, please ping the team on Discord so we can issue a GitPOAP manually. +### Philosophy -# Git standards - -## Creating commits - -Try to specify the scope of your change via a [conventional commit](https://www.conventionalcommits.org/en/v1.0.0/) (eg. `enhance(docs): improve some section`) or specifying the scope in brackets (eg. `[docs] improve some section`). - -## Submitting a PR - -Please make sure to use a conventional commit in your PR title (eg. `feat(scope): description of feature`). This will be squashed and merged into the `main` branch. - -## GitHub Actions - -Each commit will automatically trigger the GitHub Actions to run. If any commit message in your push or the HEAD commit of your PR contains the strings [skip ci], [ci skip], [no ci], [skip actions], or [actions skip] workflows triggered on the push or pull_request events will be skipped. - -# Documentation style guide - -Many standards are adopted from [Google dev docs highlights](https://developers.google.com/style/highlights). - -## Philosophy - -- Create the [minimum viable documentation](https://google.github.io/styleguide/docguide/best_practices.html#minimum-viable-documentation). +- Create the minimum viable documentation. - Don't repeat yourself, use links to existing documentation or inherit it. -- Keep documentation close to what it's describing, also called high cohesion (eg. describing a smart contract should be documented as comments in the source code). +- Keep documentation close to what it's describing (for example, in the source code). -## Document types +### Document types Group documentation under one of the four categories (adopted from [Diátaxis](https://diataxis.fr/)): -- Tutorials -- Guides +- How to - Concepts +- Tutorials - Reference -## Tone and content - -- [Use descriptive link text](https://developers.google.com/style/link-text). -- [Write accessibly](https://developers.google.com/style/accessibility). -- [Write for a global audience](https://developers.google.com/style/translation). - -## Language and grammar - -- [Use second person](https://developers.google.com/style/person): "you" rather than "we". -- [Use active voice](https://developers.google.com/style/voice): make clear who's performing the action. -- [Put conditional clauses before instructions](https://developers.google.com/style/clause-order), not after. - -## Formatting, punctuation, and organization - -- [Use sentence case](https://developers.google.com/style/capitalization) for document titles and section headings. -- [Use numbered lists](https://developers.google.com/style/lists#types-of-lists) for sequences. -- [Use bulleted lists](https://developers.google.com/style/lists#types-of-lists) for most other lists. -- [Use description lists](https://developers.google.com/style/lists#types-of-lists) for pairs of related pieces of data. -- [Use serial commas](https://developers.google.com/style/commas). -- [Use unambiguous date formatting](https://developers.google.com/style/dates-times). - -## Source code comments - -Follow the [NatSpec format](https://docs.soliditylang.org/en/v0.8.16/natspec-format.html) for documenting smart contract source code. Please adhere to a few additional standards: - -- Choose `/** */` over `///` for multi-line NatSpec comments, to save column space -- Omit the usage of `@notice`, this will be automatically picked up so it will save column space and improve readability -- Take advantage of inheritance for docs (such as documenting the interface), if you need to specify inherited docs use `@inheritdoc` - -## Images +### Images - Use SVG files or crushed PNG images. - Provide alt text. diff --git a/packages/website/docs/alpha-1-testnet/configure-wallet.mdx b/packages/website/docs/alpha-1-testnet/configure-wallet.mdx index 5cf42054453..b41ac1e3c73 100644 --- a/packages/website/docs/alpha-1-testnet/configure-wallet.mdx +++ b/packages/website/docs/alpha-1-testnet/configure-wallet.mdx @@ -8,7 +8,7 @@ import AddEthereumChainButton from "../../src/components/AddEthereumChainButton" ## Automatically add networks -Use the buttons below to add Ethereum A1 and Taiko A1 to any wallet that supports `wallet_addEthereumChain` (e.g., MetaMask). +Use the buttons below to add Ethereum A1 and Taiko A1 to any wallet that supports `wallet_addEthereumChain` (for example, MetaMask). | Network | Add to wallet | | ----------- | --------------------------------------------------------------- | diff --git a/packages/website/docs/alpha-1-testnet/deploy-a-contract.md b/packages/website/docs/alpha-1-testnet/deploy-a-contract.md index 7125e758af4..0a4535578a3 100644 --- a/packages/website/docs/alpha-1-testnet/deploy-a-contract.md +++ b/packages/website/docs/alpha-1-testnet/deploy-a-contract.md @@ -26,6 +26,6 @@ These steps will show you how to deploy a smart contract to Taiko A1 using Found ``` Note: Remove "<" and ">" from -We are using the `--legacy` flag because EIP-1559 is currently disabled on Taiko. We have plans to re-enable it in the future. +We're using the `--legacy` flag because EIP-1559 is currently disabled on Taiko. We've plans to re-enable it in the future. You can use the block explorer to verify that the contract was deployed: https://l2explorer.a1.taiko.xyz/ diff --git a/packages/website/docs/alpha-1-testnet/get-help.md b/packages/website/docs/alpha-1-testnet/get-help.md index d10f4528f80..a7b7e55e3f7 100644 --- a/packages/website/docs/alpha-1-testnet/get-help.md +++ b/packages/website/docs/alpha-1-testnet/get-help.md @@ -7,6 +7,6 @@ sidebar_position: 8 Here are two places for you to get help: - [Post your question on GitHub Discussions](https://github.com/orgs/taikoxyz/discussions/new?category=questions) -- [Chat with us on Discord](https://discord.gg/taikoxyz) +- [Chat on Discord](https://discord.gg/taikoxyz) GitHub Discussions is preferred because your question might help others who are also running into the same issue. Conversely, you might find the answer to your problem here! diff --git a/packages/website/docs/alpha-1-testnet/request-from-faucet.md b/packages/website/docs/alpha-1-testnet/request-from-faucet.md index 8c75a9d98da..5e1fd08e0a0 100644 --- a/packages/website/docs/alpha-1-testnet/request-from-faucet.md +++ b/packages/website/docs/alpha-1-testnet/request-from-faucet.md @@ -4,11 +4,13 @@ sidebar_position: 2 # 💧 Request from faucet -## Request ETH +**ETH** -- Request ETH from Ethereum A1: https://l1faucet.a1.taiko.xyz/. -- Request ETH from Taiko A1: https://l2faucet.a1.taiko.xyz/. +- Ethereum A1: https://l1faucet.a1.taiko.xyz/ +- Taiko A1: https://l2faucet.a1.taiko.xyz/ -## Request HORSE +**HORSE** -- Select HORSE from the token dropdown on the [bridge](https://bridge.a1.taiko.xyz/) and a faucet button should appear. +1. Visit the [bridge](https://bridge.a1.taiko.xyz/) +2. Select the network as Taiko A1 and the token dropdown as HORSE +3. Click the faucet button that appears diff --git a/packages/website/docs/alpha-1-testnet/run-a-node.md b/packages/website/docs/alpha-1-testnet/run-a-node.md index cb7cd691f8f..5eb03b3d036 100644 --- a/packages/website/docs/alpha-1-testnet/run-a-node.md +++ b/packages/website/docs/alpha-1-testnet/run-a-node.md @@ -9,19 +9,19 @@ This is arguably the most important part of the testnet! Taiko is fully decentra Follow the guide at [simple-taiko-node/README.md](https://github.com/taikoxyz/simple-taiko-node/blob/main/README.md) to get started. :::note -You will only be able to run a node regularly or as a proposer. In this testnet we are not running any provers. +You will only be able to run a node regularly or as a proposer. In this testnet we're not running any provers. ::: ## System requirements -Because we are a fork of geth, you can consult the [geth minimum requirements](https://github.com/ethereum/go-ethereum#hardware-requirements), which are outlined below. +Because we're a fork of Geth, you can consult the [Geth minimum requirements](https://github.com/ethereum/go-ethereum#hardware-requirements), which are outlined below. ### Minimum: - CPU with 2+ cores - 4GB RAM - 1TB free storage space to sync the Mainnet - - (**only ~50GB for Testnet**) + - (**only ~50GB for the Taiko A1 testnet**) - 8 MBit/sec download Internet service ### Recommended: diff --git a/packages/website/docs/alpha-1-testnet/start-here.md b/packages/website/docs/alpha-1-testnet/start-here.md index 885f197d30a..9643a6e4dd9 100644 --- a/packages/website/docs/alpha-1-testnet/start-here.md +++ b/packages/website/docs/alpha-1-testnet/start-here.md @@ -6,7 +6,7 @@ sidebar_position: 0 Welcome to Taiko's Alpha-1 testnet, **Snæfellsjökull**. There are two networks involved in the testnet, which we'll define: -- **Taiko A1** is the Alpha-1 testnet release of Taiko — a fully decentralized, Ethereum-equivalent ZK-Rollup. +- **Taiko A1** is the Alpha-1 testnet release of Taiko: A fully decentralized, Ethereum-equivalent ZK-Rollup. - **Ethereum A1** is Taiko's privately deployed Ethereum network, which serves as the L1 for Taiko's Alpha-1 testnet. ## What can I do? @@ -15,7 +15,7 @@ In this testnet, you can: - 🌉 Bridge tokens between Ethereum A1 and Taiko A1. - 🤝 Send transactions (e.g., deploy contracts). -- 🌐 Run a node — this makes **you** a part of Taiko! +- 🌐 Run a node—this makes **you** a part of Taiko! - 📝 Submit feedback and be forever loved. - 🥇 Earn a POAP by using your wallet to complete any 2 of the 3 following actions by January 31st 23:59 UTC: - Use the bridge diff --git a/packages/website/docs/alpha-1-testnet/use-the-bridge.md b/packages/website/docs/alpha-1-testnet/use-the-bridge.md index 98e3de642d0..34fa58560e6 100644 --- a/packages/website/docs/alpha-1-testnet/use-the-bridge.md +++ b/packages/website/docs/alpha-1-testnet/use-the-bridge.md @@ -27,4 +27,4 @@ L2: https://l2explorer.a1.taiko.xyz/address/0xb8ea36284d1fa062cc0c969e28a49f3531 ## Bridge contract explained -Read the bridge documentation on our GitHub: https://github.com/taikoxyz/taiko-mono/tree/main/packages/protocol/contracts/bridge. +Read the bridge documentation on GitHub: https://github.com/taikoxyz/taiko-mono/tree/main/packages/protocol/contracts/bridge.