| title | description | author | ms.author | ms.date |
|---|---|---|---|---|
Create new Windows Server articles using GitHub and Visual Studio Code |
How to create new Windows Server-related articles, using GitHub and Visual Studio Code, as a Microsoft employee. |
eross-msft |
lizross |
05/02/2019 |
There are two separate locations where we keep Windows Server technical content. One of the locations is public (windowsserverdocs) while the other is private (windowsserverdocs-pr). Who you are determines which location you contribute to:
-
I'm a Microsoft employee. As a Microsoft employee, you have options, based on what you're trying to do:
-
Create a brand-new article. To create a brand-new article, you must create and set up your GitHub account and tools, fork and clone the
windowsserverdocs-prrepo, set up your remote branch, create the article, and finally create a new pull request for approval and publishing. For these instructions, continue reading this article. -
Make large changes to an existing article. To make substantial changes to an existing article, you can follow the instructions in the Edit an existing Windows Server article using GitHub and Visual Studio Code article.
-
Make minor changes to an existing article. To make minor changes to an existing article, you can follow the instructions in the Update existing Windows Server articles using a web browser and GitHub article.
-
-
I'm not a Microsoft employee. As a non-Microsoft employee, you must contribute to the public location. For information about how to do that, see the Contributing to Windows Server technical documentation article.
Before you can start working in the repo, you must create and set up your GitHub account, set up two-factor verification, and install and configure all the necessary tools. If you've already done this, you can skip down to the Fork the repository section of this article.
After you've created and set up your GitHub account and tools, you can create a personal version of your repo. This is where you will create your branches and make all your changes.
You need a local copy of the source files, so you can create pull requests from your fork to the production repository.
-
Sign in to your GitHub account and browse to the
windowsserverdocs-prGitHub repository . -
Select Fork.
-
Select your GitHub account as the fork location.
You need to clone the repo get a local copy of the repo on to your local device.
-
Go to https://github.com/settings/developers, and then select Personal access tokens from the left pane.
-
Select Generate new token, give your token a meaningful and unique name, select all the available scopes, and then select Generate token.
-
Copy the token and put it somewhere safe. You'll need this for the rest of the process and after you leave the page, you won't be able to get back to it.
-
Open a Git Bash command and change directories to where you want to store your repo. We recommend using,
C:\users\<your_name>\GitHub. -
Type the following commands using your specific information, one at a time, to clone your repo and set up your remote branches:
git clone https://<your_github_username>:<your_personal_access_token>@github.com/<your_github_username>/windowsserverdocs-pr.git cd windowsserverdocs-pr git remote add upstream https://<your_github_username>:<your_personal_access_token>@github.com/MicrosoftDocs/windowsserverdocs-pr.git git fetch upstream master
-
Run this command to make sure your remote is properly set up:
git remote -v -
You should see something like this output:
$ git remote -v origin https://github.com/<your_github_username>/windowsserverdocs-pr.git (fetch) origin https://github.com/<your_github_username>/windowsserverdocs-pr.git (push) upstream https://github.com/MicrosoftDocs/windowsserverdocs-pr.git (fetch) upstream https://github.com/MicrosoftDocs/windowsserverdocs-pr.git (push)
If your remote output doesn't look like this, you can try again by first running
git remote remove upstream.
Follow these steps to create an article.
Before you can start to work on your content, you must create a new branch in your local repo.
-
Open Git Bash and type the commands (one at a time):
cd windowsserverdocs-pr git checkout –B <name_of_your_new_branch> git push origin <name_of_your_new_branch>
[!Note] We highly recommend naming your branch something obvious and unique so you can find it again later.
After the commands finish, you'll be in your new branch and ready to create your new file. You only need to change into the
windowsserverdocs-prrepo once per instance of your Git Bash. If you close Git Bash, you will need to change directories again after you open it.
-
Open Windows Explorer, go to your GitHub directory, and create a new text file in the folder structure. Your file name must be all lowercase and separated by hyphens. For example, what-is-windows-server.md.
You must also change the file extension from .txt to .md. In the error message that appears, select Yes to save the file with the new file extension.
-
Open Visual Studio Code and go to File, select Open folder, and then go to the GitHub location of the file you created in Step 1.
-
From the Explorer pane, select your new file.
-
Add your text to the page. If you're creating a new article, make sure you Add the required metadata tags to your Windows Server-related article.
-
Select File > Save.
After you add your text to your new file, you must preview your changes to make sure they appear correctly.
-
In Visual Studio Code, select either of the Preview buttons from the upper right-hand corner.
: Switches to a full-page preview of your content.
: Opens the preview page next to your working page, side-by-side. -
Make sure your article looks how you expect it to look.
After you're sure it looks right, you can commit your changes and create a pull request for publication.
After you make sure your text looks right, you can commit your changes to your local version of your repo.
-
Open Git Bash and type the commands (one at a time, removing the OPTIONAL tags):
OPTIONAL: git status git add . git commit -m “public comment about what change is” OPTIONAL: git pull upstream master git push origin <name_of_your_new_branch>
The optional git status command shows you which files have been modified as part of this commit. The optional git pull upstream master pulls down the latest content changes from the MicrosoftDocs master branch, syncing your local content with the primary master content. This helps to show you any potential merge conflicts ahead of time so you can fix them before you get to the PR stage.
After you've completed your article, you must get approval from your writer (allow some time for this) for publication.
-
Browse to the
windowsserverdocs-prGitHub repository and select the Pull requests tab. -
In the Reviewers area of the right pane, select the gear icon, and then enter the windowsservercontent alias for review.
A member of the windowsservercontent alias will review your changes or add comments about things that must be changed before merging can happen.
-
Type #sign-off into the comments so that the reviewers know you're handing off for both review and publishing. The #sign-off comment:
-
Updates the label for your pull request from do-not-merge to ready-to merge.
-
Lets the alias and writers know that you're ready to have your content reviewed.
-
Lets the admins know that after approval, your content is ready go live.
[!Important] After you add the #sign-off comment, a member of the windowsservercontent team will review the text and push it to master so it will go out with the next scheduled publish to live (10:30am and 3:30pm weekdays).
If you don't add #sign-off as a final comment to your PR, your content will remain in the queue without being pushed to Master and ultimately to Live.
-
For more information about GitHub and the markdown language, see: