From 9216c7a33b59d2206718b35ba7e9747eea9c2772 Mon Sep 17 00:00:00 2001 From: Alexandra Tran Carrillo <12214231+alexandratran@users.noreply.github.com> Date: Mon, 24 Jul 2023 12:15:59 -0700 Subject: [PATCH] Update `CONTRIBUTING.md`, etc. (#858) --- CONTRIBUTING.md | 107 +++++++++++---------------------- README.md | 2 +- docusaurus.config.js | 4 +- snaps/how-to/develop-a-snap.md | 2 +- snaps/how-to/manage-keys.md | 2 +- snaps/index.mdx | 2 +- wallet/index.md | 2 +- 7 files changed, 43 insertions(+), 78 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4ea18b442f6..b8fa32b92cd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,16 +1,18 @@ # Contribute to the documentation Thank you for your interest in contributing to the MetaMask developer documentation! +These docs generally follow the [Consensys docs guide](https://docs-template.consensys.net/). +This page describes contribution guidelines specific to MetaMask, and refers to the Consensys docs +guide in some places. ## Table of contents - [Contribution workflow](#contribution-workflow) - - [Preview locally](#preview-locally) +- [Preview locally](#preview-locally) - [Style guide](#style-guide) - - [Images](#images) -- [Markdown guide](#markdown-guide) - - [Simplified tabs](#simplified-tabs) - - [Live code blocks](#live-code-blocks) +- [Add images](#add-images) +- [Format Markdown and MDX](#format-markdown-and-mdx) + - [Live code blocks](#live-code-blocks) ## Contribution workflow @@ -36,6 +38,17 @@ To contribute changes: git clone https://github.com/MetaMask/metamask-docs.git ``` + > **Note**: If you don't have write access to this repository, you must [fork the + > repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo#forking-a-repository) + > to your personal account and clone your forked repository instead. + > [Add an upstream remote](https://docs.github.com/en/get-started/quickstart/fork-a-repo#configuring-git-to-sync-your-fork-with-the-upstream-repository) + > to be able to pull from and push to the original repository. + > + > ```bash + > git clone https://github.com//metamask-docs.git + > git remote add upstream https://github.com/MetaMask/metamask-docs.git + > ``` + 3. [Create and checkout a topic branch](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging), naming it appropriately. We recommend including the issue number and a short description in the branch name (for example, @@ -49,18 +62,19 @@ To contribute changes: 4. Open this repository in a text editor of your choice (for example, [VS Code](https://code.visualstudio.com/)) and make your changes. - Refer to the [style guide](#style-guide) and [Markdown guide](#markdown-guide) when making - documentation changes. + Make sure to [follow the style guidelines](https://docs-template.consensys.net/contribute/style-guide) + and [format your Markdown correctly](https://docs-template.consensys.net/contribute/format-markdown). > **Notes:** > - All documentation content is located in the `wallet` and `snaps` directories. > - If you add a new documentation page, make sure to edit `wallet-sidebar.js` or - `snaps-sidebar.js` to [add the page to the sidebar](https://docusaurus.io/docs/sidebar/items). - > - If you delete, rename, or move a documentation file, make sure to add a redirect to the - [redirect plugin](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-client-redirects) - in `docusaurus.config.js`. + > `snaps-sidebar.js` to add the page to the + > [sidebar](https://docs-template.consensys.net/contribute/configure-docusaurus#sidebar). + > - If you delete, rename, or move a documentation file, make sure to add a + > [redirect](https://docs-template.consensys.net/contribute/configure-docusaurus#redirects). -5. [Preview your changes locally](#preview-locally) to check that the changes render correctly. +5. [Preview your changes locally](https://docs-template.consensys.net/contribute/preview) to check + that the changes render correctly. 6. Add and commit your changes, briefly describing your changes in the commit message. Push your changes to the remote origin. @@ -87,79 +101,30 @@ To contribute changes: If you don't have merge access, a maintainer will merge your PR for you. You can delete the topic branch after your PR is merged. -### Preview locally - -As a prerequisite, make sure you have the following installed: - -- [Node.js](https://nodejs.org) version 16+ - - If you're using [nvm](https://github.com/creationix/nvm#installation) (recommended), running - `nvm use` automatically chooses the right Node.js version for you. -- [Yarn](https://yarnpkg.com/getting-started/install) version 3 - - Run `yarn install` to install dependencies and run any required post-install scripts. +## Preview locally -Preview your changes locally by running `yarn start` in the documentation repository. - -> **Note:** If you make changes to the -[redirects](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-client-redirects), you can -preview them by running `yarn build && yarn serve`. +[Preview the docs locally using npm or Yarn.](https://docs-template.consensys.net/contribute/preview) ## Style guide -The MetaMask documentation follows the -[ConsenSys documentation style guide](https://docs-template.consensys.net/getting-started/style-guide) -and the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/). -Refer to those guides for any questions on writing style. +Refer to the [Consensys documentation style guide](https://docs-template.consensys.net/contribute/style-guide). -### Images +## Add images All images are located in the `wallet/assets` and `snaps/assets` directories. When adding a new image, such as a screenshot or diagram, make sure the image has a white or `#1b1b1d` color background in order for it to be compatible with the site's light and dark modes. -## Markdown guide +Additionally, follow the [Consensys guidelines on adding images](https://docs-template.consensys.net/contribute/add-images). + +## Format Markdown and MDX The documentation is built using [Docusaurus](https://docusaurus.io/), which is powered by [MDX](https://mdxjs.com/), an extension to [Markdown](https://www.markdownguide.org/) that allows -you to use JavaScript in your documentation content. -See the [Docusaurus documentation](https://docusaurus.io/docs/markdown-features) on how to use its -Markdown and MDX features. - -> **Tip:** [Admonitions](https://docusaurus.io/docs/markdown-features/admonitions), -[tabs](https://docusaurus.io/docs/markdown-features/tabs), and -[code blocks](https://docusaurus.io/docs/markdown-features/code-blocks) are frequently used in the -MetaMask documentation. +you to use [React JSX](https://www.w3schools.com/react/react_jsx.asp) in your Markdown content. -The following sections describe features that aren't documented in the Docusaurus documentation. - -### Simplified tabs - -The [`remark-docusaurus-tabs`](https://github.com/mccleanp/remark-docusaurus-tabs) plugin allows you -to add content in [tabs](https://docusaurus.io/docs/markdown-features/tabs) using simplified syntax. - -For example, add code blocks to tabs as follows: - -````jsx - - -# HTML - -```html - -``` - -# JavaScript - -```javascript -// JavaScript code block -``` - -# Markdown - -- This is an example Markdown list. -- This is **bold** and *italicized* text. - - -```` +Follow the [Consensys guidelines on formatting Markdown](https://docs-template.consensys.net/contribute/format-markdown). +The MetaMask docs also use a plugin to implement [live code blocks](#live-code-blocks). ### Live code blocks diff --git a/README.md b/README.md index fd197a0f5fd..aeb3fd0d608 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # MetaMask developer documentation This is the MetaMask developer documentation repository. -The documentation site is hosted at [docs.metamask.io](https://docs.metamask.io/wallet), and it's +The documentation site is hosted at [`docs.metamask.io`](https://docs.metamask.io), and it's built using [Docusaurus](https://docusaurus.io/), a static site generator purpose-built for technical documentation. diff --git a/docusaurus.config.js b/docusaurus.config.js index 4833d5c6c94..9bc7761d526 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -288,7 +288,7 @@ const config = { title: "Community", items: [ { - label: "ConsenSys Discord", + label: "Consensys Discord", href: "https://discord.gg/consensys", }, { @@ -323,7 +323,7 @@ const config = { ], }, ], - copyright: `© ${new Date().getFullYear()} MetaMask • A ConsenSys Formation`, + copyright: `© ${new Date().getFullYear()} MetaMask • A Consensys Formation`, }, prism: { theme: codeTheme, diff --git a/snaps/how-to/develop-a-snap.md b/snaps/how-to/develop-a-snap.md index 9e3278dcfb1..2fde0adf6d1 100644 --- a/snaps/how-to/develop-a-snap.md +++ b/snaps/how-to/develop-a-snap.md @@ -109,7 +109,7 @@ You can review the growing number of [example snaps](https://github.com/MetaMask/snaps-monorepo/tree/main/packages/examples) maintained by MetaMask, as well as the following fully functional and open source snaps: -- [StarkNet](https://github.com/ConsenSys/starknet-snap) +- [StarkNet](https://github.com/Consensys/starknet-snap) - [FilSnap for Filecoin](https://github.com/Chainsafe/filsnap/) - [Password Manager Snap](https://github.com/ritave/snap-passwordManager) - [Transaction Simulation with Ganache](https://github.com/Montoya/tx-simulation-with-ganache-snap) diff --git a/snaps/how-to/manage-keys.md b/snaps/how-to/manage-keys.md index 92d4a3624ec..f4b24866c2a 100644 --- a/snaps/how-to/manage-keys.md +++ b/snaps/how-to/manage-keys.md @@ -109,4 +109,4 @@ For example, to derive Dogecoin keys: The following are examples of existing snaps that manage accounts and keys: - [KeystoneHQ's Btcsnap](https://github.com/KeystoneHQ/btcsnap-1) -- [ConsenSys's Starknet Snap](https://github.com/ConsenSys/starknet-snap) \ No newline at end of file +- [Consensys's Starknet Snap](https://github.com/Consensys/starknet-snap) \ No newline at end of file diff --git a/snaps/index.mdx b/snaps/index.mdx index d52a3b37dc6..84da8544eeb 100644 --- a/snaps/index.mdx +++ b/snaps/index.mdx @@ -87,4 +87,4 @@ Features include: If you have questions about using Snaps or want to propose a new feature, you can interact with the Snaps team and community on [GitHub discussions](https://github.com/MetaMask/snaps-monorepo/discussions) -and the Snaps channel on [ConsenSys Discord](https://discord.gg/consensys). +and the Snaps channel on [Consensys Discord](https://discord.gg/consensys). diff --git a/wallet/index.md b/wallet/index.md index 1940beec65d..9c10ff17ca7 100644 --- a/wallet/index.md +++ b/wallet/index.md @@ -43,4 +43,4 @@ Mobile wallet to make the connection. ## Questions? If you have questions about integrating your dapp with MetaMask, you can interact with the MetaMask -team and community on the MetaMask channels on [ConsenSys Discord](https://discord.gg/consensys). +team and community on the MetaMask channels on [Consensys Discord](https://discord.gg/consensys).