Skip to content

Latest commit

 

History

History
215 lines (136 loc) · 11 KB

CONTRIBUTING.md

File metadata and controls

215 lines (136 loc) · 11 KB
Raw

To-do

Thank you for investing your time in contributing to our project! Any contribution you make will be reflected on help.status.im.

This guide provides an overview of the different types of contributions and the contribution workflow. Read the Status Code of Conduct to keep this place approachable and respectable.

Independently of how you contribute, your contribution is considered a documentation issue and included in the Status documentation project.

TL;DR: if you know what to do, skip to the Contribute using a pull request section.

How to contribute

You can contribute using GitHub issues or pull requests.

GitHub issues

You can create a new issue or solve an existing one via pull request. If you work on an existing documentation issue, submit a pull request, and link the pull request to the issue on the GitHub website.

Issues without a triage label are pending review, and you shouldn't begin work on them.

Pull request

A pull request is a way to suggest changes in our documentation repository. If you spot an inaccuracy in our docs or you would like to submit additional content, use this method.

You can submit a pull request from a topic in the Status documentation using the edit edit button. This is the preferred method for small fixes or typos. If you want to contribute with new content, submit a pull request following the Contribute using a pull request section steps.

How we work with issues or pull requests

Consider this information:

  • We prioritize issues or pull requests related to documentation errors over the rest.
  • We triage your issue or pull request after submission and assign the triage label to it.
  • Issues or pull requests that don't fit into a technical documentation criterion will be discarded with the invalid label.
  • Issues or pull requests outside of the scope of the Status user documentation project will be discarded with the wontfix label.
  • We use the GitHub issue or pull request number to uniquely identify a task.

Because pull requests are issues, issue and pull request numbers do not overlap in a repository (see Issue event types for more information.)

Support

If you find an error using the Status app please, don't open a documentation issue. Instead, open an issue with the corresponding team at Status:

About Status Help translations

We are an international team with contributors and users from all over the world. Therefore, we know that providing documentation in multiple languages is crucial. Unfortunately, as a small team, we're unable to provide a translation workflow or add translations to our docs at this time. If you wish to contribute to the translation of other parts of the Status Network, see translate.status.im.

Install Material for MkDocs and preview your changes

We use Material for MkDocs to build the user documentation site. If you want to preview your contributions as they will look in Status Help, you need to install Material for MkDocs and its dependencies.

You don't need to install Material for MkDocs to edit Markdown files in the Status Help repo. However, it's a good idea to install Material for MkDocs and make sure your content previews correctly.

Install Python dependencies:

pip install -r requirements.txt

⚠️ WARNING: You'll need access to the private mkdocs-material-insiders fork.

To preview your changes, go to the root folder in your Status Help clone (by default, this is the help.status.im folder in your computer) and run the MkDocs live preview:

mkdocs serve -f config/[language]/mkdocs.yml`

Where [language] corresponds to the language folder name in the Status Help repository.

⚠️ Calls to mkdocs need to be done from the root folder of your Status Help repo clone.

About Material for MkDocs Insiders

For the Status Help repository, we use Materials for MkDocs Insiders, a sponsored-only version with additional functionality. Using these functionalities requires access to a private Material for MkDocs build, which is unavailable for contributors. However, we use only a few components from the Insider's version that shouldn't affect your contributions:

Contribute using a pull request

Here you can find a step-by-step guide to make changes to our docs. This process describes the git and GitHub CLI instructions.

Summary

  • Fork and clone the status-im/help.status.im repository.
  • Use the develop branch to create your topic branch.
  • Push your changes to the status-im/help.status.im repository and develop branch.
  • Propose changes using pull requests. Add a description to your pull requests.
  • If the pull request fixes an existing issue, link the pull request to the issue.

1. Fork and clone this repository

To understand how a repository fork works, see About forks in the GitHub documentation.

  1. Using the terminal, go to the directory where you want to clone the Status documentation repository.

  2. Fork and clone the repository:

    gh repo fork 'status-im/help.status.im' --remote --clone=true

2. Create a topic branch and commit changes to your own branch

  1. Update your local develop branch with the latest changes from upstream:

    git pull upstream develop --rebase --verbose
    git push origin develop

  2. Using the develop branch, create a topic branch to include your changes

    git checkout -b your-topic-branch-name develop

    Use a descriptive name for your feature branch, separating words with dashes. If you know the issue number, include this in the branch name. Examples: fix-typo-on-creating-status-communities, 133-wrong-table-values.

  3. Using the editor of your choice, write the required changes.

    If you have doubts about how to write something, check the Status style guide.

4. Test your changes

You can test your proposed changes using MkDocs live preview.

  1. Install Material for MkDocs on your computer.

  2. Using the terminal, change to the site configuration directory for your language. For example, if you're changing content under the doc/en directory, go to the config/en in the help.status.im repository.

  3. Run the live preview server:

    mkdocs serve

  4. The output of this command shows a URL with the IP address and port where the live preview server is running. Example:

    INFO - [13:48:18] Serving on [http://127.0.0.1:8000/help/en/](http://127.0.0.1:8000/help/en/)

  5. Open your browser and enter the URL.

With the Mkdocs live preview server, you can preview your changes as you write your documentation. The server will automatically rebuild the site upon saving.

5. Commit and push your work to your own fork

  1. Stage your changes:

    git add --all

  2. Commit your changes with a description of what's included:

    git commit -m "description of your changes"

  3. Set the upstream to push your changes:

    git push --set-upstream origin your-topic-branch-name

  4. If you need to add more changes, you don't need to set the upstream branch again:

    git push

6. Submit your pull request

  1. Create a pull request with your proposed changes:

    gh pr create --base develop --title "your pull request title"

  2. If prompted for the base repository, select status-im/help.status.im:

    ? Which should be the base repository (used for e.g. querying issues) for this directory?  [Use arrows to move, type to filter]
> **status-im/help.status.im**
  github-user/help.status.im

  3. When asked for the Body, type e to launch the default terminal editor. Include a description of the proposed changes:

    ? Body [(e) to launch nano, enter to skip]

    You can also skip this step and add the pull request description using the GitHub webpage.

  4. In the What's next question, select Submit to submit your pull request, or Continue in browser to finish your pull request in the GitHub website:

    ? What's next?  [Use arrows to move, type to filter]
> **Submit**
  Continue in browser
  Add metadata
  Cancel

  5. On the GitHub website, enable the checkbox to allow maintainer edits for the pull request so the branch can be updated for a merge.

  6. If your pull request is related to an existing issue, link the pull request to the issue on the GitHub website.

7. What's next?

  • We may ask for changes to be made before a PR can be merged, either using suggested changes or pull request comments.
  • As you update your PR and apply changes, mark each conversation as resolved.

Congratulations on making it this far! The Status team thanks you.

-->