Pull Requests
=============

Note: this is a primer on the mechanical steps of making a pull request. See XGC Coding Guidelines for information on what the content of a good PR looks like.

When your code changes are ready to be merged into “master”, first update the “master” branch in your working copy from the remote repository. Make sure that “master” of the remote repo, which is a fork of the XGC parent repo, has been updated from the fork’s parent repo; if necessary, ask the fork owner to do this. The fork owner can update master in his fork with

.. code-block:: bash

       git checkout master
       git pull https://[username]@github.com/PrincetonUniversity/XGC-Devel.git master
       git push origin master

Or alternatively (if you configured “upstream” as explained earlier in this document):

.. code-block:: bash

       git fetch upstream
       git checkout master
       git merge upstream/master
       git push origin master

If you are not the fork owner, ask the fork owner to update master of the fork; then 

.. code-block:: bash

       git checkout master
       git pull origin master
       git checkout [username/branch name]

Then merge “master” into your branch:

.. code-block:: bash

       git merge master

This step will show you whether there are some conflicts that you need to resolve. After finishing the merge and resolving all conflicts, push the result of the merge to the remote repo (consider pulling first as described above): 

.. code-block:: bash

       git push origin [username/branch name]

This workflow prevents situations in which a pull request has conflicts. A pull request with conflicts cannot be merged. Then create a pull request from your branch into the “master” branch in the XGC parent repo online with the GitHub GUI by navigating to the tab “Pull Requests” and clicking “New Pull Request’. A dialog will open that lets you select the origin and the target branch/repo of the pull request (Fig. 9 and 11). Again, the pull request should be from your feature branch ``[username/branch name]`` in the fork to the branch “master” in the XGC parent repo (Fig. 11). After the pull request has been merged, the fork owner needs to update “master” in the fork from the parent repo. This prevents situations in which there are differing versions of “master” in the parent repo and the forks. 

In the following dialog, you can enter a description of the changes that you want to be pulled, and you can choose reviewers for your pull request (Fig. 10). The list of reviewers should always include a repo admin who will merge the pull request after all reviewers have approved it. 


.. image:: ./img/comparing_changes.png
   :target: ./_images/comparing_changes.png
   :alt: Open Pull Request


*Creating a pull request between branches in the same repository.*


.. image:: ./img/open_pull_request.png
   :target: ./_images/open_pull_request.png
   :alt: Open Pull Request 2


*Entering a description of the changes to be pulled and choosing reviewers.*

There may be situations, in which it becomes necessary to merge branches (other than “master”) inside the same fork or between different forks. This is possible with GitHub and it is highly recommended to use pull requests in these simulations.


.. image:: ./img/open_pull_request2.png
   :target: ./_images/open_pull_request2.png
   :alt: Open Pull Request 3


*Opening a pull request from a fork to the forks parent repository.*


.. toctree::
   :maxdepth: 3