Git Flow for Writing a Learn Module

1-learn-setup.md

Preparing to Write a Learn Module

Setting Up

The first step is to fork the Learn repository so you have a forked repository that you can control.

What you'll do:

• install the gh CLI
• fork the repo
• clone your fork
• connect to the upstream (the official Learn repo)
• make your own branch

Steps:

1. Install the gh CLI

2. Fork https://github.com/MicrosoftDocs/learn-pr and clone it to your computer (this is your origin)

   gh repo fork MicrosoftDocs/learn-pr --clone

3. Change your directory to your local folder

   cd learn-pr

4. Connect to official learn-pr repo (this is your "upstream")

   git remote add upstream [email protected]:MicrosoftDocs/learn-pr.git

5. Run git remote -v and make sure your remote looks like this

   # origin  [email protected]:johnpapa/learn-pr (fetch)
   # origin  [email protected]:johnpapa/learn-pr (push)
   # upstream        [email protected]:MicrosoftDocs/learn-pr.git (fetch)
   # upstream        [email protected]:MicrosoftDocs/learn-pr.git (push)

6. Make your own branch

   git checkout -b YOUR-LEARN-MODULE-BRANCH

Create Your Pull Request

You will want to create a Pull Request from your fork repository and the branch you created, against the official Learn repository's master branch.

What you'll do:

• Create the pull request

Steps:

1. Checkout and Push your changes to your fork

   git checkout YOUR-LEARN-MODULE-BRANCH
   git push

2. Create a pull request from your branch to MicrosoftDocs/master using the gh CLI

   gh pr create -f

2-learn-daily.md

Daily Routine with Git

Every day you work on your Learn module it helps to follow a similar routine. This guide walks through those steps.

Starting Your Daily Workflow

Every day you work on your Learn module you should synchronize with the many changes that have occurred in the official Learn repo (your upstream). This will help you avoid any merge conflicts.

What you'll do:

• Synchronize your local master with the upstream master
• Push your local master to your fork
• Merge all master changes into your Learn module's branch

Steps:

1. Get the latest for your origin and upstream master branches

   git checkout master
   git pull upstream master

2. Make sure your master origin is in sync with your upstream and your local is pushed

   git pull && git push

3. Checkout your branch for your Learn module and pull the latest

   git checkout YOUR-LEARN-MODULE-BRANCH
   git pull

4. Merge master with your Learn branch. This will sync your branch all changes in the upstream master, which may be a lot. It should resolve all issues automatically.

   git merge master
   git push

Committing Your Daily Changes

As you work on your Learn module you will want to see the results from the many checks and tests that the Learn team has created, and view your Learn module in a browser.

What you'll do:

• Commit your changes
• Push your changes to your fork
• View your changes via the links in the Pull Request in the GitHub.com UI

Steps:

1. Checkout your branch for your Learn module

   git checkout YOUR-LEARN-MODULE-BRANCH

2. After doing some work locally in your branch, commit the changes

   git add .
   git commit -m "your commit message goes here"

3. Push your changes. This will update your Pull Request which will kick off all of the checks and tests that the Learn process requires (using Azure DevOps)

   git push

4. View your Pull Request in GitHub. Here you will see the results of the Learn checks and tests. You will also see links to view your Learn module.

   gh pr view

Seems obvious to us now but you might want to add the fact you must Push your changes before you can create a pull request.

I'll also be adding:

• links to how to connect to the MicrosoftDocs and learn-pr repo
• possibly vs code commands (as I use these for convenience)
• images for each flow

Seems obvious to us now but you might want to add the fact you must Push your changes before you can create a pull request.

Thanks! I added a step for that.