forked from MetaMask/metamask-docs
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add contribution guidelines (MetaMask#52)
* Add contribution guidelines * edits * more edits * minor edits
- Loading branch information
1 parent
650ec8e
commit 2465934
Showing
1 changed file
with
137 additions
and
64 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,100 +1,173 @@ | ||
| # MetaMask Docs | ||
| # MetaMask developer documentation | ||
|
|
||
| This is the MetaMask documentation repo. It's built on [Docusaurus](https://docusaurus.io/), a static site generator purpose-built for technical documentation. | ||
| This is the new MetaMask developer documentation repository. | ||
| It's built on [Docusaurus](https://docusaurus.io/), a static site generator purpose-built for | ||
| technical documentation. | ||
|
|
||
| ## Features | ||
| All documentation content is located in the `wallet` and `snaps` directories. | ||
|
|
||
| Our instance of Docusaurus uses multiple of its powerful features, including: | ||
| > **Important:** This is an alpha version of the new documentation. | ||
| The site is published temporarily at | ||
| [metamask.github.io/mm-docs-v2/staging](https://metamask.github.io/mm-docs-v2/staging/). | ||
|
|
||
| * [Multi-instance](https://docusaurus.io/docs/docs-multi-instance): we have two instances of docs, one for the API & SDK, and one for Snaps | ||
| * [Versioning](https://docusaurus.io/docs/versioning): the Snaps documentation is exposed in two versions, "current" and "next". This allows us to send developers to either of these two versions based on whether they're using a nightly build of Flask, or the officially published extension | ||
| * [MDX](https://docusaurus.io/docs/markdown-features/react#importing-markdown) | ||
| * [Custom Sidebars](https://docusaurus.io/docs/sidebar): normally sidebars are auto-generated based on the docs directory structure. Having a custom sidebar allows us to define the order and inclusion of documentation items, with any hierarchy we want. The current proposed hierarchy is here: https://docs.google.com/spreadsheets/d/1fr1qnP830Zrdbzq0rPvoTVQsYBwL2Sq-wEJjL4tGfM8/edit | ||
| ## Contribution workflow | ||
|
|
||
| ## Getting Started | ||
| All the documentation is in the form of Markdown files located in the `docs` directory. To add a new document: | ||
| The MetaMask documentation contribution workflow involves proposing changes by creating | ||
| [branches](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches) | ||
| and | ||
| [pull requests (PRs)](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) | ||
| on this repository. | ||
| This facilitates open contributions, testing, and peer review. | ||
|
|
||
| 1. Create the `.md` file in an appropriate location in the `docs` directory, and add your content | ||
| 2. Edit the `sidebars.js` file to add the document to its appropriate place in the sidebar. | ||
| To contribute changes: | ||
|
|
||
| ## Setup | ||
| 1. Search for an [existing issue](https://github.com/MetaMask/mm-docs-v2/issues) to work on, or | ||
| [create a new issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-an-issue) | ||
| describing the content issue you'd like to address. | ||
| Make sure no one else is assigned to the issue, and assign yourself to it. | ||
| If you don't have permission to assign yourself to it, leave a comment on the issue. | ||
|
|
||
| - Install [Node.js](https://nodejs.org) version 16 | ||
| - If you are using [nvm](https://github.com/creationix/nvm#installation) (recommended) running `nvm use` will automatically choose the right node version for you. | ||
| - Install [Yarn v3](https://yarnpkg.com/getting-started/install) | ||
| - Run `yarn install` to install dependencies and run any required post-install scripts | ||
| 2. [Clone](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) | ||
| this repository to your computer. | ||
|
|
||
| ## Running locally | ||
| ```bash | ||
| git clone https://github.com/MetaMask/mm-docs-v2.git | ||
| ``` | ||
|
|
||
| `yarn start` | ||
| 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, | ||
| `183-doc-cli-option`), which is a reminder to fix only one issue in a PR. | ||
|
|
||
| ## Migrating documentation from the `MetaMask/metamask-docs` repo | ||
| For the most part, Markdown files in the `MetaMask/metamask-docs` repo can be copied directly. However, a few things are to be noted: | ||
| ```bash | ||
| git checkout -b <ISSUE-NUM>-<ISSUE-DESC> | ||
| ``` | ||
|
|
||
| * The new documents won't appear in the sidebar automatically. An entry has to be added in the `sidebars.js` file to make that happen | ||
| * Any custom Vue component will need to be migrated to React | ||
| * You'll need to migrate the admonitions | ||
| * `::: admonition` becomes `:::admonition` (without the space) | ||
| * Available admonitions are: `note`, `tip`, `info`, `caution`, `danger`. Any others will have to be adjusted to the available ones | ||
| * The `:::: tabs` and `::: tab` admonitions will have to be migrated to [MDX Tabs](https://docusaurus.io/docs/markdown-features/tabs) | ||
| * Embedded code will have to be migrated to [Live Code Blocks](#live-code-blocks). | ||
| > **Tip:** You can use a Git client such as [Fork](https://fork.dev/) instead of the command line. | ||
|
|
||
| ## Preview builds | ||
| 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. | ||
|
|
||
| Generate a preview build of a PR by making a comment starting with `@metamaskbot publish-preview`. The contents of the PR will be published as a preview, then linked in a PR comment. | ||
| > **Note:** 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). | ||
|
|
||
| Note that this feature is only available for branches on this repository. If you're working from a fork, you'll have to build locally to preview your work. | ||
| 5. [Preview your changes locally](#preview-locally) to check that the changes render correctly. | ||
|
|
||
| ## MDX | ||
| 6. Add and commit your changes, briefly describing your changes in the commit message. | ||
| Push your changes to the remote origin. | ||
|
|
||
| ### Tabs | ||
| Tabs are documented here: https://docusaurus.io/docs/markdown-features/tabs | ||
| ```bash | ||
| git add * | ||
| git commit -m "<COMMIT-MESSAGE>" | ||
| git push origin | ||
| ``` | ||
|
|
||
| #### Markdown in Tabs | ||
| One thing that's not documented is how to properly do Markdown inside tabs. For example, to properly embed a list inside a tab item, one has to skip lines around the JSX tags, and un-indent the list. Otherwise, the 4 spaces will be mistaken as the start of a pre-formatted block: | ||
| 7. On [this repository on GitHub](https://github.com/MetaMask/mm-docs-v2), you’ll see a banner | ||
| prompting you to create a PR with your recent changes. | ||
| Create a PR, describing your changes in detail. | ||
| [Link the issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) | ||
| that your PR fixes by adding `fixes #<ISSUE-NUM>` to the PR description. | ||
|
|
||
| ```jsx | ||
| <Tabs> | ||
| <TabItem value="apple" label="Apple" default> | ||
| 8. Generate a preview build of your PR by adding a PR comment starting with `@metamaskbot publish-preview`. | ||
| MetaMask Bot publishes the PR as a site preview, then links it in a PR comment. | ||
| This allows reviewers to easily preview the changes made in your PR. | ||
|
|
||
| - This is a markdown apple 🍎 | ||
| - This is **meow** | ||
| 9. Specific reviewers are automatically requested when you submit a PR. | ||
| You can request additional reviewers in the right sidebar of your PR – for example, the original | ||
| issue raiser. | ||
| Make any required changes to your PR based on reviewer feedback, repeating steps 4–6. | ||
|
|
||
| 10. After your PR is approved by two reviewers, all checks have passed, and your branch has no | ||
| conflicts with the main branch, you can merge your PR. | ||
| 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. | ||
| </TabItem> {/* notice **two** skipped lines above*/} | ||
| <TabItem value="orange" label="Orange"> | ||
| This is an orange 🍊 | ||
| </TabItem> | ||
| <TabItem value="banana" label="Banana"> | ||
| This is a banana 🍌 | ||
| </TabItem> | ||
| </Tabs> | ||
| ``` | ||
| ### 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. | ||
|
|
||
| ### Live Code Blocks | ||
| Preview your changes locally by running `yarn start` in the documentation repository. | ||
|
|
||
| Rather than implementing our own live code blocks, we use the [`remark-codesandbox`](https://github.com/kevin940726/remark-codesandbox/) Remark plugin. This allows us to define a code block that will be loaded live in a CodeSandbox iframe, by adding a meta to the codeblock, like ` ```javascript codesandbox=vanilla` | ||
| ## Style guide | ||
|
|
||
| This allows us to keep our code blocks versioned and in our codebase, while giving us the full power of CodeSandbox to showcase any example we want, with any dependency we want. | ||
| 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. | ||
|
|
||
| The plugin allows for simple codeblocks where the content of the block replaces the CodeSandbox entry point, or more complex examples that can be loaded directly from the filesystem, by using `codesandbox=file:./example-folder`, as detailed in the plugin's documentation. | ||
| ## Markdown guide | ||
|
|
||
| ## Styling | ||
| Docusaurus 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. | ||
|
|
||
| In this repository, we use design tokens [implemented here](https://github.com/MetaMask/design-tokens). These design tokens are available as CSS variables, which makes it easy for developers to use them in their code. | ||
| > **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. | ||
|
|
||
| By using design tokens, we ensure consistency in the design of the Metamask user interface across different platforms and devices. To use the design tokens in your code, simply reference the CSS variables in your styles. | ||
| The following sections describe features that aren't documented in the Docusaurus documentation. | ||
| For example, to use the primary color of the Metamask design, you would use the following CSS code: | ||
| ### Code inside tabs | ||
| The simplest way to add code or Markdown inside [tabs](https://docusaurus.io/docs/markdown-features/tabs) | ||
| is to un-indent the content and tags, and add blank lines around the content. | ||
| For example: | ||
| ````jsx | ||
| <Tabs> | ||
| <TabItem value="html" label="HTML"> | ||
| ```css | ||
| color: var(--color-text-default); | ||
| ```html | ||
| <!-- HTML code block --> | ||
| ``` | ||
| You can refer to all design tokens in the [design-tokens](https://github.com/MetaMask/design-tokens/blob/main/src/css/design-tokens.css) repository. | ||
| </TabItem> | ||
| <TabItem value="javascript" label="JavaScript"> | ||
| ## Publishing | ||
| ```javascript | ||
| // JavaScript code block | ||
| ``` | ||
| </TabItem> | ||
| <TabItem value="markdown" label="Markdown"> | ||
| - This is an example Markdown list. | ||
| - This is **bold** and *italicized* text. | ||
| </TabItem> | ||
| </Tabs> | ||
| ```` | ||
| ### Live code blocks | ||
| Every commit to `main` is published automatically to GitHub pages under `/staging`. | ||
| The [`remark-codesandbox`](https://github.com/kevin940726/remark-codesandbox/) plugin allows you to | ||
| define a code block to be loaded live in a CodeSandbox iframe. | ||
| This enhances the documentation by keeping the code blocks versioned and in the codebase, while | ||
| using CodeSandbox to showcase any example with any dependency. | ||
| The `/latest` version of the package tracks the `prod` branch. The typical workflow would be to merge `main` into `prod` to update `/latest`. | ||
| Define a live code block by adding a `codesandbox` key to the code block. | ||
| For example: | ||
| ````jsx | ||
| ```javascript codesandbox=vanilla | ||
| // JavaScript live code block | ||
| ``` | ||
| ```` | ||
| `remark-codesandbox` allows for simple code blocks where the content of the block replaces the | ||
| CodeSandbox entry point, and more complex code blocks that can be loaded directly from the | ||
| filesystem. | ||
| See the | ||
| [`remark-codesandbox` documentation](https://github.com/kevin940726/remark-codesandbox/#documentation) | ||
| for more information. |