Marfeel Docs

# Contributing to MarfeelDocs

Marfeel uses a Pull Request based process to review changes before they’re added to Marfeel’s GitHub repository. Anyone with access to a repository can open a pull request.

Since docs are hosted on source code repositories the approval workflow is the same as any code related change. For more information about how to create a PR check out Cloning the repository section.

Product Managers are responsible for approving and reviewing every new document (as defined in the Codeowners file) in order to verify that all the styling and writing conventions are respected.

The main navigation structure is code owned by the Ada team.

# Branching and PR

When working on the Marfeel documentation, you can choose between two major styles of working:

  1. Work directly in the GitHub UI section, using the “Edit this File” and commit capabilities without having to clone the repository. This is useful for quick documentation updates, typo fixes, and lightweight Markdown changes.
  2. Clone the Marfeel Docs repo (opens new window) and get the site up and running locally. This is necessary for more thorough documentation content and infrastructure changes. Learn how to get set up using the Marfeel docs setup instructions.

# Edit using the GitHub UI

All articles can be edited by clicking the Edit this page in GitHub button, located at the bottom of each article.

  1. Click on the Edit this page in GitHub button.
  2. Make the desired changes in the article.
  3. Once satisfied with the changes, go to the bottom of the GitHub UI page and click the commit changes button.
  4. Select an appropriate title for the Pull Request and click the Create pull request button. This will automatically prompt the article for review to the codeowners.
  5. Once your changes are approved, click the Squash and Merge button.
  6. To deploy your code in production, trigger the build (opens new window) and then the shuttle (opens new window) will be triggered automatically (if MarfeelDocs build succeeded).
  7. Check your changes are OK in production.

# Cloning the repository

If you prefer to do the changes within the repository folder locally, follow these instructions:

WARNING

This procedure assumes you have already created a repository on GitHub, or have an existing repository owned by someone else you'd like to contribute to. If you are using Github for the first time, the SSH key needs to be added. Refer to this Github's ssh configuration article (opens new window) for more information.

  1. On GitHub, navigate to the main page of the repository.
  2. Under the repository name, click the green Code button.
  3. Use the Clone with HTTPS option, copy the clone URL for the repository.

Clone HTTPS

  1. Open the terminal.
  2. Change the current working directory to the location where you want the cloned directory to be made.
  3. Type git clone, and then paste the URL you copied in Step 3.
$ git clone git@github.com:Marfeel/RepositoryName.git
  1. Press Enter. Your local clone will be created.
  2. Create a new branch. For docs-only changes, use:
$ git checkout -b docs/some-change
  1. Edit the desired Markdown files in the /docs folder of the repository.
  2. Validate your changes are also reflected in the sections.json file when needed.

Once you've done all your changes you'll have to commit the changes and submit a pull request.

  1. Add the files to the commit. From your repository main folder:
$ git add .
  1. Commit your changes.
$ git commit -m "Explain your changes here"
  1. Push your branch.
$ git push -u origin docs/some-change

  1. Enter into Github and locate your repository.

  2. Click on Compare & pull request. Note: Ensure that the status shows 'Able to merge' (in green).

Compare & pull request button

`master` or `pre`?

Content directly targeting the main Docs website should be merged onto the master branch, whereas content which is still a work in progress should target the pre branch.

Choose a base branch

  1. You have the option to add any comments if required. Then click on Create pull request.

Create pull request button

  1. Wait for a couple of minutes and verify that all checks have passed. You should then see the following screen:

All checks have passed button

  1. Wait until your reviewer has approved your changes.

GitHub desktop app

Using GitHub desktop app (opens new window) is a hybrid of the options above. We won't cover its flow in this article, but feel free to use it if you don’t want to use the terminal.

# Markdown Linting

If you edit files from your local environment, you can benefit from linting for your markdown files. Marfeel uses markdownlint-cli (opens new window) rules, with additional custom rules defined in Marfeel Coding Standards (opens new window).

Marfeel repositories using NPM usually have a markdown linter integrated:

If you're writing in a repository that doesn't have it, setting it up in VSCode is an alternative. We recommend the markdownlint extension (opens new window).

Ignore some warnings

Markdownlint default configuration sends warnings that Marfeel tolerates.

For example, it is expected for MarfeelDocs to have both a frontmatter title and an H1 in a document:

markdown lint warnings

← Writing conventions →