Setting up your environment
Below instructions explain how you can prepare your environment to use the Office 365 Developer Patterns and Practices source but also how you can contribute.
The first step is registering yourself on GitHub. Go to https://github.com/ and click on the "Sign up for GitHub" button. Once you're registered ensure you're logged on with your new account and navigate to the Office 365 Developer Patterns and Practices repository at https://github.com/OfficeDev/PnP. The right top side of the page contains a button called "Fork":
Clicking on this button will Fork the Office 365 Developer Patterns and Practices (PnP from on) repository to your GitHub account. It's actually like taking a copy. This action takes a few seconds:
Once the forking has been done you'll find the PnP repo under your account with an URL like this one: https://github.com/jansenbedemo/PnP. Before we move to Visual Studio 2013 to clone the repository you'll nee d to first copy the git url which you can find here:
This url is the same as the repository url, but then with a .git at the end as shown here: https://github.com/jansenbedemo/PnP.git.
Before you can open the code in Visual Studio 2013/2015 you'll need to clone the repository. This is something that can be done from within Visual Studio 2013/2015. In Visual Studio open the Team Explorer, go to the "Local Git Repositories" section and enter the url of forked PnP repository plus select a directory that will contain the local copy of the PnP repository.
Click on the Clone button to trigger the cloning:
Once the cloning is done you can use the Windows Explorer to navigate to your local copy:
At this point you've a local copy of the master branch. However development in PnP happens against the dev branch or against a branch inheriting from the dev branch. Following section explain how you prepare your local PnP clone for development and contribution.
As previously mentioned you need to develop against a branch that originates from the dev branch because pull requests will only be accepted if they're issued against the PnP dev branch. The master branch is a stable branch that we monthly update with changes from the dev branch. To set up this tracked dev branch we're going to use the git command line. To do this go to Team Explorer in Visual Studio, click the Actions button and then choose "Open Command Prompt":
In the command prompt that type the following commands.
git remote add --track dev upstream https://github.com/officedev/pnp
git fetch upstream
Next step is adding a dev branch in your local repository that has as origin the upstream/dev branch which is the dev branch of the main PnP repository (the one you've forked in the first step). To do use the following command:
git checkout -b dev upstream/dev
In case you get an error like "fatal: A branch named 'dev' already exists." you can simply point the existing dev branch to the upstream dev branch via:
git branch -u upstream/dev
Since this branch is tracking a remote branch that you're not allowed to commit changes to you'll need to create your branches for changes. It's strongly advised to create a branch per feature/sample/change that you plan to do because you can only create one pull request per branch (see later). Below command creates a branch of the tracked dev branch with name feature1.
git checkout -b feature1 dev
At this point you're ready to develop, but it's required that you publish your feature1 branch to the github server, this way you're code is stored centrally which means that other can work with your code but also that when your machine is lost your code isn't and this step is required if you want to create a pull request later on. Go to Visual Studio 2013/2015, open the Team Explorer and click on the right arrow next to the repository name. This will show a menu in which you can select "Settings":
Click on "Settings" and ensure your username and email address are correctly set:
Final step is publishing the feature1 branch. Go via Team Explorer, Branches and right click the feature1 branch:
If you want to publish your branch via command line then use the following:
git push --set-upstream origin feature1
In the previous chapter you've setup a tracking branch which you now can use to update the feature branches you have in your forked repository. To refresh the feature1 branch with the latest developments in the PnP dev branch you can use the following steps:
git fetch upstream
git checkout feature1
git merge upstream/dev
Alternative approach is that you always keep your local dev branch in sync using above approach and then merge this dev branch with the feature branches that require it. If you then create a new feature branch of the dev branch you're at least sure that you start with a actual state of the PnP dev branch.
It's strongly advised to perform this step before you submit a pull request as this will avoid most of the merge conflict resolution that the core team needs to go though and as such it will also speed up the acceptance of your submissions. To lean more about how to submit pull requests checkout Preparing a contribution and letting the PnP core team know via pull request.