Setting up your environment

Bert Jansen edited this page Apr 11, 2016 · 4 revisions

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.

Forking the Office 365 Developer Patterns and Practices repository

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.

Cloning your forked PnP repository

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.

Adding a tracked dev branch to your forked PnP repository and prepare for development

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

Syncing your forked repository to keep it up-to-date with the upstream repository

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.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.