From fd9367239f87f36cbdcc6c502c235816cffeed7b Mon Sep 17 00:00:00 2001
From: Pete Travis <immanetize@fedoraproject.org>
Date: May 18 2016 03:35:27 +0000
Subject: [PATCH 1/3] begin describing pull request workflow


---

diff --git a/en-US/pull_requests.adoc b/en-US/pull_requests.adoc
new file mode 100644
index 0000000..e938acb
--- /dev/null
+++ b/en-US/pull_requests.adoc
@@ -0,0 +1,24 @@
+= Pull Requests
+
+== Workflow
+
+The sources for Fedora's documentation are stored in git repositories at https://pagure.io.  Contributions are accepted via `pull requests`, which merge changes from your copy of the repository into the original.
+
+- Install the required `tools`.
+  // I don't know how to do cross document links, or I would here.
+
+- Log into `pagure` and click the `Fork` button at the upper right hand corner of a repository.  
+  You now have a personal copy of the repo.
+
+- Clone your repository using the SSH URL.
+
+  ...
+  git clone ssh://git@pagure.io/forks/immanetize/documentation-guide.git
+  ...
+
+- Make your changes using the editor of your choice.  Add a commit for each distinct change.
+
+  ...
+  git add en-US/pull_requests.adoc
+  git commit -m 'begin describing pull request workflow'
+  ...

From 58873c6c1c64b10590b25c46825ba40b47c05cf2 Mon Sep 17 00:00:00 2001
From: Pete Travis <immanetize@fedoraproject.org>
Date: May 18 2016 04:22:00 +0000
Subject: [PATCH 2/3] wrap up pull request workflow


---

diff --git a/en-US/pull_requests.adoc b/en-US/pull_requests.adoc
index e938acb..8bdbd73 100644
--- a/en-US/pull_requests.adoc
+++ b/en-US/pull_requests.adoc
@@ -5,20 +5,45 @@
 The sources for Fedora's documentation are stored in git repositories at https://pagure.io.  Contributions are accepted via `pull requests`, which merge changes from your copy of the repository into the original.
 
 - Install the required `tools`.
-  // I don't know how to do cross document links, or I would here.
+  
+// I don't know how to do cross document links, or I would here.
 
 - Log into `pagure` and click the `Fork` button at the upper right hand corner of a repository.  
-  You now have a personal copy of the repo.
+  You now have a personal copy of the repo, called a `fork`.
 
 - Clone your repository using the SSH URL.
 
-  ...
-  git clone ssh://git@pagure.io/forks/immanetize/documentation-guide.git
-  ...
+....
+git clone ssh://git@pagure.io/forks/immanetize/documentation-guide.git
+cd documentation-guide
+....
+
+- Create a branch to contian your work.  This makes it easier for others to pull from your repo 
+  without disrupting their existing content.  You can name the branch anything, but something
+  that correlates to the work you'll be doing is best.
+
+....
+git checkout -b pull_request_workflow
+....
 
 - Make your changes using the editor of your choice.  Add a commit for each distinct change.
 
-  ...
-  git add en-US/pull_requests.adoc
-  git commit -m 'begin describing pull request workflow'
-  ...
+....
+git add en-US/pull_requests.adoc
+git commit -m 'begin describing pull request workflow'
+....
+
+- Push your changes to `pagure`.
+
+....
+git push
+....
+
+- The new branch will now appear in your fork on pagure.  Once you have pushed a cohesive set of changes,
+  press the `New PR` button to start a new pull request.  `pagure` will send your changes for review after
+  you fill out the form and press `Create`.
+
+- Work with your reviewer to address any concerns.  Subsequent commits pushed to this branch of your fork
+  will be automatically included in the pull request.
+
+- Your changes get merged by the reviewer.  Congratulations!  Reward yourself with a beer, you've earned it!

From b7bf8b06e634f2468b1a5da794ed3e4ba70d1ca8 Mon Sep 17 00:00:00 2001
From: Pete Travis <immanetize@fedoraproject.org>
Date: May 18 2016 04:24:05 +0000
Subject: [PATCH 3/3] add note about --set-upstream


---

diff --git a/en-US/pull_requests.adoc b/en-US/pull_requests.adoc
index 8bdbd73..c2d40aa 100644
--- a/en-US/pull_requests.adoc
+++ b/en-US/pull_requests.adoc
@@ -36,9 +36,11 @@ git commit -m 'begin describing pull request workflow'
 - Push your changes to `pagure`.
 
 ....
-git push
+git push --set-upstream origin pull_request_workflow
 ....
 
+NOTE: The `--set-upstream` option is only required when pushing a new branch.
+
 - The new branch will now appear in your fork on pagure.  Once you have pushed a cohesive set of changes,
   press the `New PR` button to start a new pull request.  `pagure` will send your changes for review after
   you fill out the form and press `Create`.