Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
254 lines (157 loc) · 9.37 KB

CONTRIBUTING.md

File metadata and controls

254 lines (157 loc) · 9.37 KB
permalink /CONTRIBUTING.md
title Contributing

Contribute to the Documentation Content

Who can contribute?

Anyone who has a GitHub account can contribute to the documentation content:

Can I build the documentation locally?

No, this repository only hosts the documentation site content, and does not include any of the frontend or backend components required to build or render the site. Internal Scaleway users must refer to the dedicated internal guidelines to build previews of the documentation.

How to contribute?

Prerequisites

Contribution procedure for internal Scaleway users

Important

  • All rules below concern this repository.
  • Any PRs which do not comply with the rules below will be rejected.

  1. Run the command below in a terminal to clone the repository and access it:

    git clone git@github.com:scaleway/docs-content.git && cd docs-content

  2. Make sure you have identified the type of content that you want to write or edit (e.g. tutorial, API/CLI documentation, additional content or troubleshooting).

  3. Run the command below to create a local Git branch:

    git checkout -b name-of-my-branch

    All branch names must comply with the following naming convention: [source]-[action]-[product].

    • source: Either int (for internal Scaleway contributors) or ext (for external contributors).

    • action: The action you will perform in the documentation, described in 3 letters or less: add for adding content, rm for removing content, or fix to fix typos.

    • product: the name of the product that corresponds to the documentation page you will edit.

    ℹ️ Example: in the branch int-add-instances, an internal contributor will add information to a documentation page of the Instances product category.

  4. Make your edits to the documentation. Refer to the writing guidelines to ensure your changes comply with our style guide.

  5. Run the command below to stage your changes before committing them:

    git add path/to/files

  6. Run the command below to create a new commit containing the changes previously staged. Refer to the commit naming conventions below to properly name your commit.

    git commit -m "docs(product): description with some words"

  7. Run the command below to push your changes to the remote repository:

    git push --set-upstream origin <YOUR_BRANCH_NAME>

  8. Go to the pull requests page to open a pull request.

    All pull requests names must comply with the following naming convention: docs(product_name): description with some words.

Important

All PRs are reviewed and approved by the Scaleway Product Documentation team before being merged by them.

Contribution procedure for external users

Important

  • All rules below concern this repository.
  • Any PRs which do not comply with the rules below will be rejected.

  1. Access the docs-content repository, and click Fork in the top right corner. A form appears.

  2. Keep the default values in the form, and click Create Fork.

  3. Make sure you have identified the type of content that you want to write or edit (e.g. tutorial, API/CLI documentation, additional content or troubleshooting).

  4. Run the command below to create a local Git branch:

    git checkout -b name-of-my-branch

    All branch names must comply with the following naming convention: [source]-[action]-[product].

    • source: Either int (for internal Scaleway contributors) or ext (for external contributors).

    • action: The action you will perform in the documentation, described in 3 letters or less: add for adding content, rm for removing content, or fix to fix typos.

    • product: the name of the product that corresponds to the documentation page you will edit.

    ℹ️ Example: in the branch ext-add-instances, an external contributor will add information to a documentation page of the Instances product category.

  5. Make your edits to the documentation. Refer to the writing guidelines to ensure your changes comply with our guidelines.

  6. Run the command below to stage your changes before committing them:

    git add path/to/files

  7. Run the command below to create a new commit containing the changes previously staged. Refer to the commit naming conventions below to properly name your commit.

    git commit -m "docs(product): description with some words"

  8. Run the command below to push your changes to the remote repository:

    git push --set-upstream origin <YOUR_BRANCH_NAME>

  9. Go to the pull requests page to open a pull request.

  10. Click Create pull request, then select

  • base repository: scaleway/docs-content

  • base: main

  • head repository: <your-account>/docs-content

  • compare: <your-branch-with-changes>

  1. Click Create pull request.

    All pull requests names must comply with the following naming convention: docs(product_name): description with some words.

Important

All PRs are reviewed and approved by the Scaleway Product Documentation team before being merged by them.

Reference

Git commit

Helpful pre-commit commands:

  • pnpm check-slugs Output slugs that are not kebab-case well formatted.

Commit conventions

This project uses conventional commits based on the Angular convention.

Here is a commit template example:

type(module): description with some words PROJECT-XXX

Lowercase only, (module) is optional. Adding the project number at the end is recommended.

Here is the list of type to use (commons in bold):

  • docs
    • Do not use other than project docs itself concerns (like README file)
  • feat
    • Add new materials (page, sections, …)
  • fix
    • For instance, fix typos, images, …
  • refactor
    • In rare cases, for instance if you have to change folders structures.
  • revert
    • Oops case, if you want to redo previous history state
  • style
    • For simple format changes that are not content changes

Commit examples

feat(console): add vpc how-to page MTA-2342

fix(iot): wrong image in quickstart

style: add bold at scaleway name occurrences MTA-1337

Markdown

Markdown is a lightweight markup language for creating formatted text using a plain-text editor.

Files with markdown content usually use the .md extension.

As we need to use evolved dynamic and designed blocks, for the Scaleway Documentation platform, the choice was to use the extended markdown format, with a special .mdx extension.

With MDX files traditional markdown content can be used with React components.

MDX components

MDX components are useful for adding rich content and interactions within your contributions.

Tip

See the full Components page.

Feel free to explore this page in your markdown editor to see how the components were used, or in .mdx content files that already use MDX components.

Frontmatter

Any Markdown file that contains a YAML frontmatter block will be processed by Gatsby as a special file. The front matter must be the first thing in the file and must take the form of a valid YAML set between triple-dashed lines.

Here is a common example used in our .mdx files:

---
title: How to create a Bare Metal server
description: This page explains how to create a Bare Metal server
tags: compute baremetal bare metal cloud server dedicated
dates:
  validation: 2021-06-22
  posted: 2020-03-12
categories:
  - compute
---

Here starts the content…
  • title and description, used for SEO, Algolia & for h1 and description in pages
  • tags are used to help populate search result lists or pages top. Use space separators.
  • dates are shown on pages under titles. validation must be a date later than the posted. Its format should be AAAA-MM-DD.

Writing Guidelines

Refer to the Scaleway Documentation Guidelines for an extensive list of our writing guidelines.