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:>
Clement Verna 0afe07
ready to contribute to the project.
Jeremy Cline 0b19fd
Kamil Páral 2a3318
Pagure to Pagure pull request
Clement Verna 0afe07
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Jeremy Cline 0b19fd
Clement Verna 0afe07
You can create a pull request from a pagure project, using one of the following options
Jeremy Cline 0b19fd
Kamil Páral 2a3318
From the project overview
Clement Verna 0afe07
*************************
Jeremy Cline 0b19fd
Clement Verna 0afe07
#. Go the the ``overview`` tab of your fork.
Clement Verna 0afe07
Clement Verna 0afe07
#. Locate your feature branch (Right hand side), and press the button ``New PR`` button.
Clement Verna 0afe07
Clement Verna 0afe07
#. Fill the Create a pull request form (Title and Description) and create your pull request.
Clement Verna 0afe07
Clement Verna 0afe07
Notes: The ``New PR`` button appears only if there are commits not available in the main branch.
Clement Verna 0afe07
Clement Verna 0afe07
.. image:: _static/pagure_pr_overview.png
Clement Verna 0afe07
	:target: ../_images/pagure_pr_overview.png
Clement Verna 0afe07
Kamil Páral 2a3318
From the commits history
Clement Verna 0afe07
************************
Clement Verna 0afe07
Clement Verna 0afe07
#. Go to the ``commit`` tab of your fork and select your feature branch.
Clement Verna 0afe07
Clement Verna 0afe07
#. Press the ``create pull request`` button (above the latest commits).
Clement Verna 0afe07
Clement Verna 0afe07
#. Fill the Create a pull request form (Title and Description) and create your pull request.
Clement Verna 0afe07
Clement Verna 0afe07
.. image:: _static/pagure_pr_commits.png
Clement Verna 0afe07
	:target: ../_images/pagure_pr_commits.png
Clement Verna 0afe07
Clement Verna 0afe07
From the pull requests list
Clement Verna 0afe07
***************************
Clement Verna 0afe07
Clement Verna 0afe07
#. Go to the main project's (not your fork) pull requests list and press the ``File Pull Request`` button.
Kamil Páral 2a3318
Kamil Páral 2a3318
#. Select the feature branch containing your changes from the dropdown menu.
Clement Verna 0afe07
Clement Verna 0afe07
#. Fill the Create a pull request form (Title and Description) and create your pull request.
Clement Verna 0afe07
Clement Verna 0afe07
.. image:: _static/pagure_pr_pull_requests.png
Clement Verna 0afe07
	:target: ../_images/pagure_pr_pull_requests.png
Kamil Páral 2a3318
Kamil Páral 2a3318
Remote Git to Pagure pull request
Clement Verna 0afe07
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Clement Verna 0afe07
René Genz ec0022
You can create a pull request from another git hosting platform (e.g. GitHub, GitLab).
Clement Verna 0afe07
This is a remote pull request.
Clement Verna 0afe07
Clement Verna 0afe07
From the pull requests list
Clement Verna 0afe07
***************************
Clement Verna 0afe07
Clement Verna 0afe07
#. Go to the main project's (not your fork) pull requests list and press the ``File Pull Request`` button.
Kamil Páral 2a3318
Clement Verna 0afe07
#. Select the ``Remote pull-request`` option from the dropdown menu.
Clement Verna 0afe07
Kamil Páral 2a3318
#. Fill the New remote pull-request form (Title, Git repo address and Git branch) and create your remote pull request.
Clement Verna 0afe07
Clement Verna 0afe07
Congratulations! It is now up to the project maintainer to accept your changes
Clement Verna 0afe07
by merging them.
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
Clement Verna ea0206
it or to test it. You can do this by editing your git configuration as follow.
Kamil Páral 2a3318
Locate your remote in the ``.git/config`` file, for example::
Clement Verna ea0206
Kamil Páral 2a3318
    [remote "origin"]
Clement Verna ea0206
        url = ssh://git@pagure.io/pagure.git
Kamil Páral 2a3318
        fetch = +refs/heads/*:refs/remotes/origin/*
Kamil Páral 2a3318
Kamil Páral 2a3318
Now add this line::
Kamil Páral 2a3318
Kamil Páral 2a3318
    fetch = +refs/pull/*/head:refs/remotes/origin/pr/*
Clement Verna ea0206
Kamil Páral 456808
to that section as **the first fetch line**, like this::
Clement Verna ea0206
Kamil Páral 2a3318
    [remote "origin"]
Clement Verna ea0206
        url = ssh://git@pagure.io/pagure.git
Kamil Páral 2a3318
        fetch = +refs/pull/*/head:refs/remotes/origin/pr/*
Kamil Páral 456808
        fetch = +refs/heads/*:refs/remotes/origin/*
Clement Verna ea0206
René Genz ec0022
Obviously, the remote URL should be matching the URL of your project (pagure project in
Clement Verna ea0206
this example).
Clement Verna ea0206
Clement Verna ea0206
Now you can fetch the all the pull requests: ::
Clement Verna ea0206
Kamil Páral 2a3318
    $ git fetch origin
Clement Verna ea0206
    From ssh://pagure.io/pagure
Kamil Páral 2a3318
    * [new ref]        refs/pull/2541/head -> origin/pr/2541
Kamil Páral 2a3318
    * [new ref]        refs/pull/2540/head -> origin/pr/2540
Kamil Páral 2a3318
    * [new ref]        refs/pull/2538/head -> origin/pr/2538
Clement Verna ea0206
Clement Verna ea0206
To checkout a particular pull request: ::
Clement Verna ea0206
Clement Verna ea0206
    $ git checkout pr/25413
Kamil Páral 2a3318
    Branch pr/2541 set up to track remote branch pr/2541 from origin.
Clement Verna ea0206
    Switched to a new branch 'pr/2541'
Clement Verna ea0206
Clement Verna ea0206
You will now be able to use this branch to work from or on this pull requests.
Clement Verna f39e6e
Clement Verna f39e6e
If you are only interested in one particular pull request and do not want to fetch all the project PRs,
Clement Verna f39e6e
you can add to your ``~/.bashrc`` the following function: ::
Clement Verna f39e6e
Clement Verna f39e6e
    function pullpr {
Kamil Páral 2a3318
        remote="${2:-origin}"
Clement Verna f39e6e
        git fetch $remote pull/$1/head:pr_$1
Clement Verna f39e6e
        git checkout pr_$1
Clement Verna f39e6e
    }
Clement Verna f39e6e
Clement Verna f39e6e
Then after sourcing your ``~/.bashrc`` or restarting your shell, you can use the
Clement Verna f39e6e
pullpr function to checkout a pull request from within the clone of the git repository.
Clement Verna f39e6e
For example checkout pull request number 58 from current git clone (here the
Clement Verna f39e6e
infra-docs project) ::
Clement Verna f39e6e
Clement Verna f39e6e
    $ source ~/.bashrc
Clement Verna f39e6e
    $ pullpr 58
Clement Verna f39e6e
    remote: Counting objects: 393, done.
Clement Verna f39e6e
    remote: Compressing objects: 100% (238/238), done.
Clement Verna f39e6e
    remote: Total 365 (delta 231), reused 255 (delta 127)
Clement Verna f39e6e
    Receiving objects: 100% (365/365), 71.36 KiB | 63.00 KiB/s, done.
Clement Verna f39e6e
    Resolving deltas: 100% (231/231), completed with 20 local objects.
Clement Verna f39e6e
    From ssh://pagure.io/infra-docs
Clement Verna f39e6e
    * [new ref]         refs/pull/58/head -> pr_58
Clement Verna f39e6e
    Switched to branch 'pr_58'