Tool installations

Important

If you are making only minor changes to an article, you DO NOT need to complete this step and can continue directly to the minor/infrequent changes workflow.

Major contributors and Microsoft employees are encouraged to complete this step, which enables you to use the major/long-running changes workflow. Even if you have write permissions in the main repository, it is highly recommended (and this guide assumes) that you will 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 will be installing Git for Windows. You can accept all default settings, unless you want different behavior.

Git Bash install1

Git Bash install2

Git Bash install31

Git Bash install4

Git Bash install5

Note

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 will 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 user name and email locally in Git.

  1. Launch the Git Bash command prompt.

  2. Configure your user name to match the user name that you set up in your GitHub profile:

    git config --global user.name "johndoe"

  3. 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 "alias@microsoft.com"

  4. Type git config -l (that's the letter "l" and not the number "1") and review your local settings to ensure the user name and email in the configuration are correct.

Additional Git resources

Install a Markdown editor

Markdown is a light-weight markup language that is both easy to read and easy to learn. Because of this, it's rapidly become an industry standard. In order 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 Writing Essentials / Markdown section.

Important

For Microsoft contributors, the recommended Markdown editor is Visual Studio Code. Visual Studio Code is also strongly recommended for teams that require use of VSCode extensions (such as Gauntlet and Acrolinx).

Visual Studio Code

Visual Studio Code, also known as VS Code, is Microsoft's entry in this space. It's updated often and keeps getting better. Visit the Visual Studio Code documentation page to learn more about VS Code.

For Microsoft employees, the OPS engineering team also provides VS Code authoring and Acrolynx extensions to assist with authoring OPS-compliant articles for Docs.

Atom

Atom is a free Markdown editor provided by GitHub. It does not require a license for business use, and it has spell check.

If you use Atom, you'll need to set up a few things :

  1. Atom defaults to using 2 spaces for tabs, but Markdown expects 4 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 4 spaces - you can find this setting under File>Settings>Editor Settings>Tab Length.
  2. You will probably also want to turn on Soft Wrap in this section too, which does the same as "word wrap" in Notepad.
  3. To turn on the Markdown preview, click Packages>Markdown Preview>Toggle Preview. You can use Ctrl-Shift-M to toggle the preview HTML view.

Next steps

  • Microsoft employees
    • If your group requires you to use the VS Code Gauntlet authoring or Acrolynx extensions to assist with authoring OPS-compliant articles for Docs, make sure you complete the installation(s) 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 by continuing to Local repository setup, which shows you how to set up a local copy of the repository to use for your contributions.