1:22 a.m.
Authored first cut at instructions on how to use GitHub
Signed-off-by: Shawn Wells <shawn(a)redhat.com>
---
docs/Developer_Guide/en-US/ch002-Patching.xml | 110 +++++++++++++++++++++++++
1 files changed, 110 insertions(+), 0 deletions(-)
create mode 100644 docs/Developer_Guide/en-US/ch002-Patching.xml
diff --git a/docs/Developer_Guide/en-US/ch002-Patching.xml
b/docs/Developer_Guide/en-US/ch002-Patching.xml
new file mode 100644
index 0000000..3939999
--- /dev/null
+++ b/docs/Developer_Guide/en-US/ch002-Patching.xml
@@ -0,0 +1,110 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "Developer_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter id="chap-Developer_Guide-Patching">
+ <title>Patch Creation</title>
+ <para>.... intro on GitHub pull request system ..... </para>
+ <para> </para>
+ <section id="sect-Developer_Guide-Patching-maillist">
+ <title>Fork SSG </title>
+ <orderedlist>
+ <listitem>
+ <para>Visit SSG's GitHub webpage at <ulink
+ url="https://github.com/OpenSCAP/scap-security-guide"
+ >https://github.com/OpenSCAP/scap-security-guide</ulink>. In the
top-right
+ corner, you will see a button that says "Fork." Click it.</para>
+ <para><inlinegraphic
fileref="images/ch002-Patching-fork.png"/></para>
+ </listitem>
+ <listitem>
+ <para>If you're a member of multiple GitHub groups/accounts, you will be
asked for
+ the fork destination. For most users it is sufficient to fork into their local
+ account. To do so, click on your username/icon. For example:</para>
+ <para><inlinegraphic
fileref="images/ch002-Patching-forklocation.png"/></para>
+ </listitem>
+ <listitem>
+ <para>Congratulations, you've created a localized repository! Any changes
you make
+ will be localized, consider it your own sandbox. At this point you can 'git
+ clone' the source over SSH, HTTPS, or Subversion. </para>
+ <para>GitHub dynamically generates the appropriate git URLs, and dynamically
+ generates zip-compressed archives should you desire them. In the right-most
+ column, near the bottom, you will see the various git clone options:</para>
+ <para><inlinegraphic
fileref="images/ch002-Patching-githubURL.png"/></para>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section id="sect-Developer_Guide-Patching-commit">
+ <title>Committing to your Local Repository</title>
+ <para>... text to describe .... </para>
+ <section>
+ <title>Edits via GUI</title>
+ <para>The GitHub website supports in-line editing of files. This is extremely
convenient
+ when making small changes, such as fixing typos. When you've found a file in need
of
+ edits, note the "Edit" button within the file's toolbar:</para>
+ <para><inlinegraphic
fileref="images/ch002-Patching-inline_edits.png"/></para>
+ <para>This will bring you to an in-line editor. Make your changes and scroll to
the
+ bottom of the webpage. You will notice a "Commit Changes" form. The first
field is a
+ one-line description of the change, while within the second (main body) you are
+ expected to provide a detailed description of any changes. Your entries in this
+ field should be as concise as possible while providing enough description for a
+ community member to properly evaluate your changes, and the logic for making them.
+ For example:</para>
+ <para><inlinegraphic
fileref="images/ch002-Patching-GUI_naming_scheme_sample.png"
+ /></para>
+ <para>Click on "Commit changes," which will push the change to your
local
+ repository.</para>
+ </section>
+ <section>
+ <title>Edits via CLI</title>
+ <para>As mentioned earlier, GitHub creates a localized git repository, your own
personal
+ sandbox. Clone the repository locally, then 'git commit' and 'git
push' changes as
+ you normally would.</para>
+ </section>
+ </section>
+
+ <section id="sect-Developer_Guide-Patching-ssgproject">
+ <title>Issuing Pull Requests</title>
+ <para>When you're ready for your patches to be merged upstream, you must
issue a "Pull Request." </para>
+ <para>
+ <orderedlist>
+ <listitem>
+ <para>Return to your local repositories webpage on GitHub. </para>
+ <para><emphasis role="bold">NOTE: </emphasis>If
you've created local branches,
+ ensure you've selected the appropriate branch that you'd like to submit
+ patches against. <emphasis role="italic">For most people, this step
can be
+ ignored.</emphasis></para>
+ </listitem>
+ <listitem>
+ <para>Click on "Pull Request," located in the top-right of the frame
which lists
+ your directory contents:</para>
+ <para><inlinegraphic
fileref="images/ch002-Patching-Pull_Requests.png"/></para>
+ </listitem>
+ <listitem>
+ <para>You will be brought to a listing of your commits. Click the green
button
+ labelled "Create Pull Request":</para>
+ <para><inlinegraphic
fileref="images/ch002-Patching-Create_Pull.png"/></para>
+ </listitem>
+ <listitem>
+ <para>You will be requested to input a patch title and description. Be
concise,
+ but thorough enough for a community member to understand logic behind your
+ changes. Paste into the description field testing evidence (e.g. running
+ testcheck.py on any submitted OVAL, or before/after for remediation
+ scripts). </para>
+ <para>After completing the form, select "Send pull
request":</para>
+ <para><inlinegraphic
fileref="images/ch002-Patching-Send_Pull_Request.png"
+ /></para>
+ <para/>
+ </listitem>
+ <listitem>
+ <para>A community member will review your patch. They will either merge the
+ patch upstream, indicate additional changes/documentation needed, or decline
+ the patch. You'll automatically be notified via EMail of any status
+ updates.</para>
+ </listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+</chapter>
--
1.7.1