Preparing a contribution and letting the PnP core team know via a pull request
The previous "Setting up your environment" instructions got you to a git repo using the feature1 branch which is ready for your changes changes. We'll now explain how to make changes, commit them and create a pull request.
To show the edit and commit we've opened a solution and edited the documentation file (readme.md):
When you're done editing you want to commit the changes to git. Right click the solution/project and choose Commit...:
Visual Studio 2013/2015 will show the Team Explorer with the Changes page shown. Here you will see which changes are included/excluded and you'll have the option to add a commit message:
When you click Commit the change is commited to your local repository, but not yet to the github server:
Clicking on the "Sync" link will bring you to the Team Explorer page named "Unsynced Commits". On this page you can use Fetch/Pull to update your local repository with server side changes. When you do you'll see a message on top indicating the status of your repository:
Final step is pushing your changes to the github server. This is done by clicking the "Push" link:
If you prefer to this step using command line then please use:
git push origin
You created this nice new sample or fixed a bug and now you want to see your changes being included in the main PnP repository. To automate this process the concept of pull requests has been setup. You prepare your changes and notify the main PnP repository owners. They can pull your changes in the main repository, hence the name pull request.
Go to your forked repository on the github site and select your branch (e.g. feature1) you want to create a pull request for:
Click on the green button before the branch to trigger the creation of a pull request. By default github will compare your feature1 branch with the master branch in the main PnP repository.
Since the pull requests need to be submitted against the dev branch you need to edit the pull request by clicking the Edit button and then selecting the dev branch to compare against. When you do you should end up with a pull request proposal that only contains your changes:
It's best that you describe what this pull request contains so that the PnP core team better understands what you want to do.
Finally click Create pull request to create the pull request:
At this point the PnP core team will get notified and someone will pick up your pull request and either merge it or provide feedback. Not all pull request can be merged, but when your request gets rejected then you'll get the reasoning behind which will help you to submit successfull pull requests in the future. Below screenshot shows the outcome when a pull request was accepted. Note that you'll also get mails from github to keep you up to date.
Once your pull request has been accepted you can reuse this branch for a new change or just delete it and create a new branch for the next change.
Important: do not delete your branch before your PR has been accepted and merged. We sometimes pull down your branch and test your changes on our own environment. It can also happen that we want you to make some small changes to your PR and you will have to do that in your branch. If you delete your branch before the PR is merged we unfortunately cannot process your PR.
Below you'll see how you can use the Team Explorer to delete a branch:
You can also cleanup your branch using command line:
git push origin :feature1
git checkout dev
git branch –d feature1
When you've setup your forked repository you've taken a snapshot from the main PnP repository. Since the dev branch in the PnP repository is actively being updated, you'll want to frequently update your forked repository. In the previous "Setting up your environment" instructions we've setup your dev branch to track the dev branch in the main PnP repository: this makes it very easy to just fetch the updates:
Fetching shows you what updates are waiting to be pulled in, to actually get these changes in you'll need to pull the changes which updates your local repository:
Using command line this is as simple as:
git merge upstream/dev