Blame doc/usage/pull_requests.rst

Jeremy Cline 0b19fd
.. _pull-requests:
Jeremy Cline 0b19fd
Jeremy Cline 0b19fd
Pull Requests
Jeremy Cline 0b19fd
=============
Jeremy Cline 0b19fd
Pagure uses the concept of pull requests to contribute changes from your fork
Jeremy Cline 0b19fd
of a project back to the upstream project. To contribute a change to a project
Jeremy Cline 0b19fd
you first open a pull request with original project. The project maintainer
Jeremy Cline 0b19fd
then merges the pull request if they are satisfied with the changes you have
Jeremy Cline 0b19fd
proposed.
Jeremy Cline 0b19fd
Jeremy Cline 0b19fd
Jeremy Cline 0b19fd
.. _open-pull-request:
Jeremy Cline 0b19fd
Jeremy Cline 0b19fd
Open a Pull Request
Jeremy Cline 0b19fd
-------------------
Jeremy Cline 0b19fd
Before you can open a pull request, you need to complete the :ref:`first-steps`
Jeremy Cline 0b19fd
and :ref:`create-fork` of the project you would like to contribute to. Once
Jeremy Cline 0b19fd
you have a fork and you have pushed a `git branch <https: docs="" git-branch="" git-scm.com="">`_</https:>
Jeremy Cline 0b19fd
containing one or more `commits <https: docs="" git-commit="" git-scm.com="">`_, you are</https:>
Jeremy Cline 0b19fd
ready to contribute to the project. Navigate to the project's Pull Request page
Jeremy Cline 0b19fd
and click on the ``File Pull Request`` button.
Jeremy Cline 0b19fd
Jeremy Cline 0b19fd
A dropdown menu should appear containing the git branches in your fork. Select the
Jeremy Cline 0b19fd
branch containing your changes. You will be taken to a page where you can customize
Jeremy Cline 0b19fd
the title of your Pull Request and its description. By default, this is populated
Jeremy Cline 0b19fd
using your commit message.
Jeremy Cline 0b19fd
Jeremy Cline 0b19fd
Once you are satisfied with your title and description, click ``Create``.
Jeremy Cline 0b19fd
Jeremy Cline 0b19fd
Congratulations! It is now up to the project maintainer to accept your changes by
Jeremy Cline 0b19fd
merging them.
Jeremy Cline 0b19fd
Jeremy Cline 0b19fd
Jeremy Cline 0b19fd
.. _update-pull-request:
Jeremy Cline 0b19fd
Jeremy Cline 0b19fd
Updating Your Pull Request
Jeremy Cline 0b19fd
--------------------------
Jeremy Cline 0b19fd
It is likely that project maintainers will request changes to your proposed code
Jeremy Cline 0b19fd
by commenting on your pull request. Don't be discouraged! This is an opportunity
Jeremy Cline 0b19fd
to improve your contribution and for both reviewer and reviewee to become better
Jeremy Cline 0b19fd
programmers.
Jeremy Cline 0b19fd
Jeremy Cline 0b19fd
Adding to your pull request is as simple as pushing new commits to the branch you
Jeremy Cline 0b19fd
used to create the pull request. These will automatically be displayed in the
Jeremy Cline 0b19fd
commit list for the pull request.
Jeremy Cline 0b19fd
Jeremy Cline 0b19fd
Jeremy Cline 0b19fd
Rebasing
Jeremy Cline 0b19fd
^^^^^^^^
Jeremy Cline 0b19fd
You may encounter a situation where you want to include changes from the master
Jeremy Cline 0b19fd
branch that were made after you created your pull request. You can do this by
Jeremy Cline 0b19fd
`rebasing <https: docs="" git-rebase="" git-scm.com="">`_ your pull request branch and</https:>
Jeremy Cline 0b19fd
pushing it to your remote fork.
Jeremy Cline 0e256c
Jeremy Cline 0e256c
Jeremy Cline 0e256c
.. _working-with-prs:
Jeremy Cline 0e256c
Jeremy Cline 0e256c
Working with Pull Requests
Jeremy Cline 0e256c
--------------------------
Jeremy Cline 0e256c
It's quite common to work with a pull request locally, either to build on top of
Jeremy Cline 0e256c
it or to test it. Currently, the best way to do this is by adding a remote to your
Jeremy Cline 0e256c
git repository and checking out the branch the pull request is based on. For example,
Jeremy Cline 0e256c
suppose user ``jcline`` has opened a pull request on the ``pagure`` project. The
Jeremy Cline 0e256c
pull request was created using the branch name ``doc-prs-locally``. You can work with
Jeremy Cline 0e256c
the commit or commits in this pull request by doing::
Jeremy Cline 0e256c
Jeremy Cline 0e256c
    $ git remote add -f jcline https://pagure.io/forks/jcline/pagure.git  # Add and fetch the remote
Jeremy Cline 0e256c
    $ git checkout jcline/doc-prs-locally
Jeremy Cline 0e256c
René Genz 520020
You will now be in a "detached HEAD" state. If you want to build off this pull
Jeremy Cline 0e256c
request, just create a local branch, add some commits, push it to your fork,
Jeremy Cline 0e256c
and open your own pull request::
Jeremy Cline 0e256c
Jeremy Cline 0e256c
    $ git checkout -b better-docs
Jeremy Cline 0e256c
    $ git commit -m "Improve this documentation"
Jeremy Cline 0e256c
    $ git push -u origin better-docs