Skip to content

Latest commit

 

History

History
189 lines (141 loc) · 8.37 KB

CONTRIBUTING.md

File metadata and controls

189 lines (141 loc) · 8.37 KB
Raw

Contribute to the documentation

Thank you for your interest in contributing to the MetaMask developer documentation! These docs generally follow the Consensys docs guide. This page describes contribution guidelines specific to MetaMask, and refers to the Consensys docs guide in some places.

Table of contents

Contribution workflow

The MetaMask documentation contribution workflow involves proposing changes by creating branches and pull requests (PRs) on this repository. This facilitates open contributions, testing, and peer review.

To contribute changes:

  1. Search for an existing issue to work on, or create a new 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.

  2. Clone this repository to your computer and navigate into it.

    git clone https://github.com/MetaMask/metamask-docs.git
cd metamask-docs

    Note: If you don't have write access to this repository, you must fork the repository to your personal account and clone your forked repository instead. Add an upstream remote to be able to pull from and push to the original repository.

    git clone https://github.com/<YOUR-USERNAME>/metamask-docs.git
cd metamask-docs
git remote add upstream https://github.com/MetaMask/metamask-docs.git

  3. Initialize and update the submodule.

    git submodule init && git submodule update

  4. Create and checkout a topic branch, 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.

    git checkout -b <ISSUE-NUM>-<ISSUE-DESC>

    Tip: You can use a Git client such as Fork instead of the command line.

  5. Open this repository in a text editor of your choice (for example, VS Code) and make your changes. Make sure to follow the style guidelines and format your Markdown correctly.

    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.
    • If you delete, rename, or move a documentation file, make sure to add a redirect.

  6. Preview your changes locally to check that the changes render correctly.

  7. Add and commit your changes, briefly describing your changes in the commit message. Push your changes to the remote origin.

    git add *
git commit -m "<COMMIT-MESSAGE>"
git push origin

  8. On this repository on GitHub, 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 that your PR fixes by adding fixes #<ISSUE-NUM> to the PR description.

  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 5–7.

  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.

Preview locally

Preview the docs locally using npm or Yarn.

Update the submodule

This repository uses the keyring-api repository as a Git submodule.

Run the following command to initialize and update the submodule when you first clone the repository, and every time the submodule's target commit is updated:

git submodule init && git submodule update

Note: You'll see when the submodule's commit is updated when you git merge or git pull. If you have trouble previewing the docs locally, try updating the submodule.

Style guide

Refer to the Consensys documentation style guide.

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.

Additionally, follow the Consensys guidelines on adding images.

Format Markdown and MDX

The documentation is built using Docusaurus, which is powered by MDX, an extension to Markdown that allows you to use React JSX in your Markdown content.

Follow the Consensys guidelines on formatting Markdown. The MetaMask docs also use a plugin to implement live code blocks.

Live code blocks

The 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.

Define a live code block by adding a codesandbox key to the code block. For example:

```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 for more information.

Analytics

The docusaurus-plugin-segment plugin enables simple usage analytics to inform documentation improvements that may be needed.

If you need to test analytics events in your local development enviorment be sure to export the appropriate key for the environment you are testing against before building and running the project:

export SEGMENT_ANALYTICS_KEY="<your key>"

Then build the project in production mode using the following command:

yarn build && yarn serve