If you're making only minor changes to an article, you do not need to complete the steps in this article and can continue directly to the minor/infrequent changes workflow.
Major contributors and Microsoft employees are encouraged to complete these steps, which enable you to use the major/long-running changes workflow. Even if you have write permissions in the main repository, we highly recommend (and this guide assumes) that you fork and clone the repository, where you will have read/write permissions to store your proposed changes.
Install Git client tools
Install the latest version of Software Freedom Conservancy's Git client tools. This installs the Git version control system, including Git Bash, the command-line app that you will use to interact with your local Git repository.
For the purposes of this guide, we'll install Git for Windows. You can accept all default settings, unless you want different behavior.
If you prefer a graphical user interface (GUI) over a command-line interface (CLI), see Software Freedom Conservancy's available GUI Clients page, GitHub's GitHub Desktop, or Visual Studio Code for some popular options. In this guide, we'll focus on using the command-line interface.
Update your Git Bash configuration
To make sure that you are listed correctly as a contributor, you must configure your username and email locally in Git.
Open the Git Bash command prompt.
Configure your username to match the username that you set up in your GitHub profile:
git config --global user.name "johndoe"
Configure your email to match the primary email that you designated in your GitHub profile. Use your Microsoft email address:
git config --global user.email "email@example.com"
git config -l(that's the letter "l" and not the number "1"), and review your local settings to ensure the username and email in the configuration are correct.
Additional Git resources
Install a Markdown editor
Markdown is a lightweight markup language that is both easy to read and easy to learn. Because of this, it has rapidly become an industry standard. To write articles in Markdown, we recommend that you first download and install a Markdown editor.
Additional details on how to write with Markdown, including Markdown basics and the features supported by OPS custom Markdown extensions, are covered later in the How to use Markdown article.
For Microsoft contributors, the recommended Markdown editor is Visual Studio Code. Some teams require the use of Visual Studio Code extensions (such as Gauntlet and Acrolinx).
Visual Studio Code
Atom is a free Markdown editor that GitHub provides. It does not require a license for business use, and it has a spell checker.
If you use Atom, you'll need to set up a few things:
- Atom defaults to using two spaces for tabs, but Markdown expects four spaces. If you leave it at the default of two, your article will look great in local preview but not when it’s imported into Azure. So, configure Atom to use four spaces. You can find this setting under File > Settings > Editor Settings > Tab Length.
- Turn on Soft Wrap in this section. It has the same effect as Word Wrap in Notepad.
- To turn on the Markdown preview, select Packages > Markdown Preview > Toggle Preview. You can use Ctrl+Shift+M to toggle the preview HTML view.
- For Microsoft employees:
- If your group requires you to use the VS Code Gauntlet authoring or Acrolinx extensions to assist with authoring OPS-compliant articles for Docs, complete the installations before continuing.
- If your group uses the VS Code Gauntlet extension and you are a portfolio owner/administrator, please also review the Gauntlet Template Service.
- Finish the "Setup" section of this guide by continuing to Local repository setup. It shows you how to set up a local copy of the repository to use for your contributions.