I have to admit, I still consider myself a GitHub newbie.
Most of my clients use TFS or Azure DevOps and my previous experiences with GitHub were unpleasant.
But since I started contributing to the Office 365 Developer Community, I had no choice but to become familiar with GitHub.
The majority of the repositories under https://github.com/SharePoint and https://github.com/officedev -- for example -- have contributing guidelines, but they assume that you have a basic understanding of GitHub -- or at least, a better understanding of GitHub than I had when I started contributing.
Because I still hesitate with GitHub commands once in a while, I use a cheat sheet when I start a new PnP contribution. I copy and paste the GitHub commands from the cheat sheet and substitute placeholders with the values I want. It is really an amalgamation of GitHub commands from the various contributing guideline documents I have found useful into (I hope) a coherent set of instructions. I try to use the GitHub browser interface wherever I can, and GitHub commands where it is easier.
I have written this post to answer all the questions I had when I started. It is really a note for myself, but I hope it can be useful for someone else who wants to get started. While this article is written specifically for PnP contributions, they also apply to most open source contributions on GitHub.
I am not a GitHub expert. There may be better ways to do what is described in this post, but these are the instructions that have worked well for me in the past. If you have any suggestions on how to improve the instructions, please submit a comment below. I'll even buy you a coffee when you're in town!
This article focuses on the GitHub commands. If you need help with your first contribution, David Warner II has kindly volunteered to help anyone with their first PnP contribution. He's a true master on the topic.
I'm trying something new today: interactive, personalized instructions for you. Yes, you!
Instead of putting placeholders in the instructions (like [your_repo_name]) that you have to change as you follow the instructions, the placeholders are connected to a form at the top of each section.
When you change the values of the placeholders, the instructions in this post change automatically!
To get customized instructions, just replace the placeholder values with your own values.
Don't worry, we don't save any values you entered.
Let me know if you like this in the comments below. If you do, I may do more interactive posts in the future. It's kinda fun!
If you know me, you know that I love processes.
The diagram below represents the contribution process that we'll discuss today.
graph LR AA[Fork repository]-->A A[Clone repository]-->B[Create branch] B-->C[Contribute] C-->D[Push changes] D-->E[Submit pull request] E-->|Repeat|B
It consists of the following steps:
- Fork repository
- Clone repository
- Create a branch
- Push changes
- Submit pull request
- Repeat (go back to Create branch)
Step 1: Fork repository
Before you can contribute to a repository, you need to Fork it. Forking a repository creates a copy of it from the original owner's account to your own.
Once you have created your own fork, you can freely change the code in your own copy of the repository without worrying about affecting the original repository, or upstream repository. However, GitHub remembers what the upstream repository is, which will make it easy for you to submit your contributions when you're done but also to synchronize changes that have been made to the upstream repository since you forked it.
Forking only happens within GitHub; it doesn't affect the code on your machine (that is, until you clone it, but that'll happen later).
How to fork a repository
- In your browser go to http://github.com and find the repository you want to contribute to. For example, the sp-dev-fx-webparts is where you would submit SharePoint web part samples.
- In the upper right corner, select the Fork button
- If you haven't already logged in to GitHub, you'll be prompted to do so. If you haven't already created a GitHub account, you'll be able to create one. If you have already logged in, it will automatically begin the forking process. You get a cute little animation showing that it is "copying" the repository, and you end up in your own copy of the repository.
- You'll know that you're in a fork because the owner will have changed to you, and it should say "forked from ..."
The repository name should now be
[your_github_username]/[repo_name], for example, if you forked
SharePoint/sp-dev-fx-webparts and your username is
hugoabernier, your forked repository will be called
Enter your own variables
Take a second to enter the original repository URL and your GitHub username below, and the rest of this post will automatically change to match what you should see:
|Original Repository (Upstream)|
|Your GitHub username|
You have created your own fork! This is what is called an origin repository. I know, I know, the terms are confusing, but here is a table that may help break down the differences:
|What is it||The original repository||Your forked instance of a repository|
|Where is it||https://github.com/SharePoint/sp-dev-fx-webparts||https://github.com/[your_github_username]/sp-dev-fx-webparts|
|Who owns it||SharePoint (Not you!)||[your_github_username] (You)|
|What changes should you make||Create issues, submit a pull request||Whatever you want|
|What is the impact of your changes||Affects the original repository||Affects only your fork|
|Who can see your changes||Everyone||Everyone who looks at your repository, unless you made it private|
Once you have forked a repository, clicking on Fork again will do nothing; It simply redirects you to your own fork.
Step 2: Clone repository
Once you created your origin repository, it is time to clone it. Cloning a repository creates a copy of your fork to your local machine, so you can work on it.
The cloned repository, which will reside on your local hard-drive, will become your local repository; The repository that is on GitHub will be what's called your remote repository.
You can make any changes to the local files on your hard-drive, it will only affect your local repository. It won't affect your remote repository (until later, when we push the changes).
To clone your repository
- From your computer, launch whatever tool you like to run Git commands. Some people like Git Bash, but I prefer Cmder or the Node.js command prompt.
- Make sure that your command prompt is in the directory where you'll want to create your local repositories. I like to use
c:\github. You can do so by typing:
or, if using Git Bash:
- The repository you will clone will be created a directory within your current directory. To clone the repository, just type
git clonefollowed by the URL of the repository you forked in the previous section. Note that the URL should end with
git clone https://github.com/[your_github_username]/sp-dev-fx-webparts.git
It should create a directory with the same name as your repo, then should download all the files locally to that directory. It doesn't take very long, but it really depends on your internet connection. This is what it should look like:
- Once your local repo is created, change to the directory that was just created by typing
cdfollowed by the repo name and
- To link your local repo with the original upstream repo, you'll type
git remote add upstreamfollowed by the original upstream repo URL, as follows:
git remote add upstream https://github.com/SharePoint/sp-dev-fx-webparts.git
Linking to the upstream repo will make your life easier later when you want to make more contributions.
- Before you start making changes, you should make sure that you have the latest version from the original upstream repository. Of course, since you just forked the repo, you should already up to date, but if make more contributions later, you'll want to make sure you're always making your new contributions against the latest code. To do so, simply type the following:
git fetch upstream
Now you'll have a local repository with a remote that is connected to the upstream repo that we can create a branch from.
Step 3: Create a branch
In GitHub, repositories usually have multiple branches. In GitHub, a branch is a way to keep track of change by grouping them into a feature set. The
master branch is usually the default branch, where all approved code usually ends up. You normally shouldn't make changes to the
master branch directly, that's what pull requests are for.
When you want to make changes in a repo, you should create your own branch to help keep track of the changes you're making. For example, if you want to add a cool feature to a repo, you would create a branch called
cool-feature. Meanwhile, someone else may create their own branch called
coolest-feature, which may later become the basis for someone else's
Eventually, when those branches are submitted via a pull request (assuming they get approved), they'll end up being merged back to the
Most PnP repositories usually have a
dev branch, which is meant to be your starting point for your changes.
Take a moment to look in your repo for any contribution guidelines to make make sure that the starting branch is the
Once you have confirmed what branch you should start from, you should create own branch from the starting branch, and give it a name that will describe what you'll be doing in that branch. For example
hugo-patch-1. Try to avoid spaces and funny characters.
Enter your own variables
Enter the name of the branch you want to create, and we'll update the instructions for you:
|Start branch name (default is |
To create your branch
To create your branch, follow these steps:
- To create a branch, we'll start by calling
git pull upstream, which will update your local repository with the latest changes from the upstream repository. We'll also specify which branch to start from, and what to call the new branch by typing the following:
git pull upstream dev:coolerest-feature
- Now we'll let your forked origin repo know about the new branch you've created by typing
git push originfollowed by your new branch name, as follows:
git push origin coolerest-feature
- Finally, we'll switch to the new branch you've created by calling
git checkout, followed by your new branch name. Type the following:
git checkout coolerest-feature
If you're using Cmder, you should see that your prompt has changed to indicate that you're now in your new branch:
Note: If you need instructions to configure Cmder to display your repo and branch, read my earlier post
Now you're reading to contribute!
Step 4: Contribute
Now that you have your own branch, you can make the changes you need. Please make sure you follow the Microsoft Open Source code of conduct.
If you aren't sure about the code of conduct, you can also check out the [Code of Conduct FAQ] (https://opensource.microsoft.com/codeofconduct/faq/).
Once you're done making your changes, you'll want to push your contributions.
Step 5: Push your changes
As you make changes to files in your local branch, your changes will be tracked locally. Changing the files in your local folder does not affect the local repository until you commit your changes.
Once you have committed your changes to the local repository, you can push your changes to your remote repository (the one on GitHub.com).
You can do so by following these steps:
- From the local branch folder, type:
git add .
- Commit your changes by typing
git commit -v -a -mfollowed by a comment indicating what your changes were. For example, if you wanted to say "Initial commit", you would type the following:
git commit -v -a -m "Initial commit"
Now your changes are committed with a comment. Time to submit a pull request!
Step 6: Submit a pull request
In GitHub, a pull request is really simply a request for someone else to review the work that you've done and merge your changes in. When you create a pull request, you need to select two branches on GitHub, the branch that you've made your changes on, and the branch where you would want to merge your changes into.
To do so, follow these steps:
- Push your changes to your origin repository (the forked repository you created), you'll want to type
git push originfollowed by your branch name, as follows:
git push origin coolerest-feature
- Once done, use your browser to your forked repository (https://github.com/[your_github_username]/sp-dev-fx-webparts), you should see that your changes have already been reflected to GitHub.
- From your forked repository, click on Pull requests in the navigation, then click on New pull request. Optionally, you can visit https://github.com/hugoabernier/sp-dev-fx-webparts/pull/new/coolerest-feature.
- You'll be prompted to confirm the branches you want to merge, with an arrow going from one branch to another. Make sure that the arrow is pointing from your branch on your forked repo to the branch on the remote repo. If you follow all the steps above, you should also see Able to merge.
- Provide a descriptive title for your pull request. For example, New coolerest feature
- Most PnP repositories have a pull request template. Please be courteous and follow the instructions in the template. Follow the prompts and answer as much as possible. If there are sections that say
> _(DELETE THIS PARAGRAPH AFTER READING)_, delete them.
- When you have filled the template, click Create pull request.
After you've completed your pull request, you'll see that its status is marked as Open
All you have to do now is to wait for your pull request to be merged with the
It can take a few days, sometimes weeks before your pull request is approved. Please be patient; Most reviewers are volunteers and have a day-to-day job.
While you're waiting, you can start a new contribution!
Step 7: Repeat
If you want to continue making contributions, you simply create a new branch from the original base branch. For example, if you were created the second update to your
coolerest-feature, you could call your next branch
Enter your own variable
Enter the name of the next branch you want to create, and we'll update the instructions for you:
|Next branch name|
To create your next branch, follow these steps:
git pull upstreamwith your next branch name by typing the following:
git pull upstream dev:coolerest-feature-2
- Push your new branch by typing
git push originfollowed by your next branch name, as follows:
git push origin coolerest-feature-2
- Finally, switch to your new branch by calling
git checkout, followed by your next branch name. Type the following:
git checkout coolerest-feature-2
Once your next branch is created, continue contributing as you did before (contribute, push your changes, submit a pull request).
Deleting your branch
Once your pull request has been approved and merged to the
master, you can delete your branch. Do not delete your branch before it has been approved -- just in case you need to make a change to your pull request before it has been approved.
Trust me on this one.
I know, this was a long post. However, I hope that it will be useful for someone who wants to get started with making contributions to the PnP community.
For more information
There are many other resources available out there. Here are some that you should definitely check out:
- No code contributions: ([David Warner II)[https://twitter.com/davidwarnerii] See how you can provide “No Code” contributions to the Microsoft & SharePoint PnP (Patterns and Practices) Community using just your browser -- with video!.
- Community Demo - Getting started on using GitHub to contribute to SharePoint dev community: Andrew Connell walks you through how to get started. Maybe you didn't need to read this entire post after all?
- Keep Your Forked Git Repo Updated with Changes from The Original Upstream Repo: Andrew Connell explains what happens when the upstream repo has changes that occur between the time when you first forked it and when you submitted the pull request, and how to avoid such issues.
- August 23, 2019: Added For more information section, because there are many great references out there that people should know about. Also, added link to the latest list of popular PnP repositories