- Fork Office PowerShell repo to your own account.
- Clone your repo to your local development computer.
git clone [URL to your forked repo]
- Keep your forked repo up-to-date with upstream repo.
git remote add upstream https://github.com/MicrosoftDocs/office-docs-powershell.git
git fetch upstream
- Create your own working branch.
git checkout -b [name of your branch]
- Work on content in your favorite Markdown editor.
- Test to make sure your work matches the correct schema (use PlatyPS tool for this).
- Merge the Master branch with your working branch (in your forked repo) and resolve any issues.
git merge master [name of your branch]
- Submit a Pull Request to move your work upstream.
To sign in to GitHub, point your web browser to https://github.com/login.
To join GitHub for the first time, point your web browser to https://github.com/join.
It is highly recommended to turn on two-factor authentication for security, see https://help.github.com/articles/about-two-factor-authentication/.
Fork the GitHub project into your own account so you have a place to work on it. To Fork the project, point your web browser to the repository at https://github.com/MicrosoftDocs/office-docs-powershell and then click the Fork button on the upper right corner of the repository page as shown in screenshot.
You now have your very own copy (fork) of the main Office PowerShell repository. You can see it by clicking on your profile drop-down in the upper right of the page and choosing Your Profile and then clicking the Repositories tab of your GitHub account as shown in the diagram.
Your repository is an exact copy of the original Office PowerShell repository and is located in your GitHub account. In GitHub terms the main Office PowerShell repository is the Upstream repository and your forked version is the Downstream repository.
You can update your repository with the Upstream repository at any time and it is recommended to do this fairly often so that your fork doesn't get out of sync with the original. The next section covers cloning and updating your repo with the upstream repo.
Now that you have your own copy of the repository on GitHub the next step is to get the actual files on your local computer so you can work with them. To do this you clone your GitHub repository to your local computer. Here is a diagram:
Tip: You can clone your repository to muliple computers if you choose. You just have to make sure you save your local work by pushing it back up to your repository. And vice versa, when you start working on a new computer you have to remember to pull any changes down to your local work computer. This will be described in more detail later on.
There are many tools that can be used to work with GitHub. This example uses Visual Studio Code but use whatever you prefer. The concepts are the same. Visual Studio Code is available for Windows, Linux, and Mac. You can find it here: https://code.visualstudio.com/
If you have Git Bash installed you can get to it from within Visual Studio Code by pressing Control-` (control-backtick key which is to the left of number 1).
Using Visual Studio Code and Git Bash you can clone a repository as follows:
git clone [URL to your forked repo]
For example, git clone https://github.com/kenwith/office-docs-powershell.git
Note that in this example my user is kenwith so I need to make sure I am cloning the Fork I created and not the upstream original. The user is in the URL for the GitHub repo.
Once you have cloned your repository you can use git push and git pull to push and pull your changes up to your repository. It is best to use your own working branch so this will be covered in the next section.
To update your copy of the repo with the upstream copy you first need to add a remote origin and then fetch the upstream branch. There are many ways to do this but one way is to use Git Bash as follows:
git remote add upstream https://github.com/MicrosoftDocs/office-docs-powershell.git
git fetch upstream
For more details, see:
- https://help.github.com/articles/configuring-a-remote-for-a-fork/
- https://help.github.com/articles/syncing-a-fork/
The next step is to create your own working branch. The reason for this is so that you can pull updates from the Master branch from the upstream repository and merge your own working branch in your own Fork. This way you can be sure when you do a Pull Request that you won't be conflicting with edits that have happened since you forked the project.
In the Git Bash terminal in Visual Studio Code:
git checkout -b [name of your branch]
Note the -b flag creates the branch if it doesn't exist and switches to it. To checkout an existing branch leave out the -b flag.
Open your favorite Markdown editor and edit the Markdown in your working branch. Tip: Visual Studio Code provides a nice side-by-side view for editing Markdown content. One side will show the Markdown source and the other side will show a preview of how the Markdown will render. You can find this view by clicking the small icon in the upper right of Visual Studio Code that looks like a side by side view with a magnifying glass.
Some important notes when editing Markdown:
Make sure your edits match the required PowerShell schema. The schema can be found here: https://github.com/PowerShell/platyPS/blob/master/platyPS.schema.md Any deviations will break Get-Help. If you want to validate you can use the PlatyPS tool. Use the New-ExternalHelp command (from PlatyPS) on your Markdown. If there are any schema errors they will show up.
Since GitHub is a source control system and marks edits on a per-line basis it is important to have each sentence, or concept, on its own line. Markdown will still show paragraphs with each sentence on its own line. To break into another paragraph add a blank line in between the paragraphs. Here is a great article that describes this writing system: https://rhodesmill.org/brandon/2012/one-sentence-per-line/
Learn how to write good Markdown (which is a type of Markup language): https://guides.github.com/features/mastering-markdown/
More about writing content for GitHub: https://help.github.com/categories/writing-on-github/
You can find the schema that the content should follow here: https://github.com/PowerShell/platyPS/blob/master/platyPS.schema.md
Merge the Master branch with your working branch (in your forked repo) and resolve any issues. https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging
It is best practice to merge the Master branch from upstream with your working branch and not vice versa. Then you can submit a Pull Request for your working branch and the upstream repo maintainer can merge your branch into Master without issues.
Make sure that you have your working branch checked out and that your forked repo is updated with the upstream Master branch. See the section on forking above for details.
Merge the Master branch with your working branch and then resolve issues.
git merge master [name of your branch]
To get your work back into the upstream repo you create a Pull Request. A Pull Request asks the maintainers of the upstream repo to pull your work into the main project.
- To create a Pull Request, Open your web browser and navigate to the main upstream repo site at: https://github.com/MicrosoftDocs/office-docs-powershell
- Click the New Pull Request button towards the top of the page.
- Click the link to "compare across forks".
- Select the upstream branch and your local branch.
- Click Create Pull Request.
The repo maintainers will be notified of your Pull Request. Your Pull Request will have its own page where you can discuss and modify your request if required.
Once your Pull Request is approved and your branch merged into Master your changes will show up on the review.docs.microsoft.com site. Unfortunately this site requires a Microsoft login.
The next step is for a maintainer to merge the Master branch into the Live branch. Once this is done your work will show up on docs.microsoft.com.
The easiest way to find a cmdlet on docs.microsoft.com is to use the PowerShell Browser here: https://docs.microsoft.com/powershell/module If you know a cmdlet exists but doesn't show up in the PowerShell Browser search then open an Issue (link at top of this repo).
When the product team releases a new build your work will also show up in the Office products themselves when a user types Get-Help for the cmdlets that you worked on.
You just joined an elite club of contributors to Microsoft Office documentation! Your edits will be pulled into the product and show up under Get-Help when someone is viewing reference content for the cmdlet you edited. See your status here: https://github.com/MicrosoftDocs/office-docs-powershell/graphs/contributors
Don't forget to brag share on social media!
Sharing helps sustain the community and advertises to others to contribute to the open source content as well!