From 0b19fd95e5001661679ecfe4b806aba4e0f1e2f3 Mon Sep 17 00:00:00 2001 From: Jeremy Cline Date: Feb 07 2017 13:47:26 +0000 Subject: Add usage docs for forks and pull requests Signed-off-by: Jeremy Cline --- diff --git a/doc/usage/forks.rst b/doc/usage/forks.rst new file mode 100644 index 0000000..c0a778d --- /dev/null +++ b/doc/usage/forks.rst @@ -0,0 +1,65 @@ + +.. _forks: + +Forks +===== +A fork in Pagure is a copy of a repository. When contributing to a project on +Pagure, the first step is to fork it. This gives you a place to make changes +to the project and, if you so wish, contribute back to the original upstream +project. If you're not already familiar with Git's distributed workflow, +`the Pro Git book has an excellent introduction +`_. + +You can see a list of projects you've forked on your home page. + + +.. _create-fork: + +Create a Fork on Pagure +----------------------- +To fork a project, simply navigate to the project on Pagure and click +the fork button. You will then be redirected to your new fork. + + +.. _configure-local-git: + +Configure your Local Git Repository +----------------------------------- +Now that you have forked the project on Pagure, you're ready to configure a +local copy of the repository so you can get to work. First, clone the +repository. The URL for the repository is on the right-hand side of the +project overview page. For example:: + + $ git clone ssh://git@pagure.io/forks/jcline/pagure.git + $ cd pagure + +After cloning your fork locally, it's a good idea to add the upstream +repository as a `git remote `_. For +example:: + + $ git remote add -f upstream ssh://git@pagure.io/pagure.git + +This lets you pull in changes that the upstream repository makes after you +forked. Consult Git's documentation for more details. + + +Pushing Changes +--------------- +After you :ref:`configure-local-git` you're ready to make your changes and +contribute them upstream. First, start a new branch:: + + $ git checkout -b my-feature-or-bugfix + +It's a good idea to give the branch a descriptive name so you can find it later. +Next, make your changes. Once you're satisfied, add the changes to Git's staging +area and commit the changes:: + + $ git add -A # Adds everything + $ git commit -s + +Your text editor of choice will open and you can write your commit message. +Afterwords, you are ready to push your changes to your remote fork:: + + $ git push -u origin my-feature-or-bugfix + +You are now ready to :ref:`open-pull-request` diff --git a/doc/usage/index.rst b/doc/usage/index.rst index df50011..68d2048 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -33,6 +33,8 @@ Contents: :maxdepth: 2 first_steps + forks + pull_requests markdown project_settings roadmap diff --git a/doc/usage/pull_requests.rst b/doc/usage/pull_requests.rst new file mode 100644 index 0000000..da9e231 --- /dev/null +++ b/doc/usage/pull_requests.rst @@ -0,0 +1,53 @@ +.. _pull-requests: + +Pull Requests +============= +Pagure uses the concept of pull requests to contribute changes from your fork +of a project back to the upstream project. To contribute a change to a project +you first open a pull request with original project. The project maintainer +then merges the pull request if they are satisfied with the changes you have +proposed. + + +.. _open-pull-request: + +Open a Pull Request +------------------- +Before you can open a pull request, you need to complete the :ref:`first-steps` +and :ref:`create-fork` of the project you would like to contribute to. Once +you have a fork and you have pushed a `git branch `_ +containing one or more `commits `_, you are +ready to contribute to the project. Navigate to the project's Pull Request page +and click on the ``File Pull Request`` button. + +A dropdown menu should appear containing the git branches in your fork. Select the +branch containing your changes. You will be taken to a page where you can customize +the title of your Pull Request and its description. By default, this is populated +using your commit message. + +Once you are satisfied with your title and description, click ``Create``. + +Congratulations! It is now up to the project maintainer to accept your changes by +merging them. + + +.. _update-pull-request: + +Updating Your Pull Request +-------------------------- +It is likely that project maintainers will request changes to your proposed code +by commenting on your pull request. Don't be discouraged! This is an opportunity +to improve your contribution and for both reviewer and reviewee to become better +programmers. + +Adding to your pull request is as simple as pushing new commits to the branch you +used to create the pull request. These will automatically be displayed in the +commit list for the pull request. + + +Rebasing +^^^^^^^^ +You may encounter a situation where you want to include changes from the master +branch that were made after you created your pull request. You can do this by +`rebasing `_ your pull request branch and +pushing it to your remote fork.