Aug 18, 2019
Interactive Post: My GitHub cheat sheet for PnP contributions
Interactive
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/PnP have contribution 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 main 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 process consists of the following steps:
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).
The repository name should now be [your_github_username]/[repo_name], for example, if you forked pnp/sp-dev-fx-webparts and your username is hugoabernier, your forked repository will be called hugoabernier/sp-dev-fx-webparts.
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:
| Variable | Value |
|---|---|
| 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:
| Characteristics | Upstream | Origin |
|---|---|---|
| What is it | The original repository | Your forked instance of a repository |
| Where is it | https://github.com/pnp/sp-dev-fx-webparts | https://github.com/[your_github_username]/sp-dev-fx-webparts |
| Who owns it | pnp (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.
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).
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:
cd \github
or, if using Git Bash:
cd /c/github
The repository you will clone will be created a directory within your current directory. To clone the repository, just type git clone followed by the URL of the repository you forked in the previous section. Note that the URL should end with .git:
git clone https://github.com/[your_github_username]/sp-dev-fx-webparts.gitIt 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 cd followed by the repo name and [Enter]:
cd sp-dev-fx-webpartsTo link your local repo with the original upstream repo, you’ll type git remote add upstream followed by the original upstream repo URL, as follows:
git remote add upstream https://github.com/pnp/sp-dev-fx-webparts.gitLinking 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.
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 main branch is usually the default branch, where all approved code usually ends up. You normally shouldn’t make changes to the main 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 new feature to a repo, you would create a branch called my-feature. Meanwhile, someone else may create their own branch called my-cooler-feature, which may later become the basis for someone else’s most-coolest-feature branch.
Eventually, when those branches are submitted via a pull request (assuming they get approved), they’ll end up being merged back to the main branch.
Most PnP repositories usually have a main 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 main branch.
To help you, David Warner II and I have compiled a list of popular PnP repositories that will tell you which branch you should use.
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 my-feature, or hugo-patch-1. Try to avoid spaces and funny characters.
Enter the name of the branch you want to create, and we’ll update the instructions for you:
| Variable | Value |
|---|---|
Start branch name (default is main) | |
| Branch name |
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 main:my-featureNow we’ll let your forked origin repo know about the new branch you’ve created by typing git push origin followed by your new branch name, as follows:
git push origin my-featureFinally, 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 my-featureIf 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!
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.
Once you’re done making your changes, you’ll want to push your contributions.
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 -m followed 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!
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 origin followed by your branch name, as follows:
git push origin my-featureOnce 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/my-feature.
You’ll be prompted to confirm the branches you want to merge, with an arrow going from one branch tco 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 coolest 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 main branch.
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!
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 my-feature, you could call your next branch my-new-feature.
Enter the name of the next branch you want to create, and we’ll update the instructions for you:
| Variable | Value |
|---|---|
| Next branch name |
To create your next branch, follow these steps:
Calling git pull upstream with your next branch name by typing the following:
git pull upstream main:my-new-featurePush your new branch by typing git push origin followed by your next branch name, as follows:
git push origin my-new-featureFinally, switch to your new branch by calling git checkout, followed by your next branch name. Type the following:
git checkout my-new-featureOnce your next branch is created, continue contributing as you did before (contribute, push your changes, submit a pull request).
Once your pull request has been approved and merged to the main, 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.
There are many other resources available out there. Here are some that you should definitely check out: