commit 0b1847f4f8728f598d81285b0ccdf5d88282c70c
Author: Pete Travis <immanetize(a)fedoraproject.org>
Date: Tue Dec 31 00:32:57 2013 -0700
added workflow SOP for creating a patch with git
en-US/workflow-patching.xml | 321 +++++++++++++++++++++++++++++++++++++++++++
en-US/workflow.xml | 9 +-
2 files changed, 328 insertions(+), 2 deletions(-)
---
diff --git a/en-US/workflow-patching.xml b/en-US/workflow-patching.xml
new file mode 100644
index 0000000..d2e194a
--- /dev/null
+++ b/en-US/workflow-patching.xml
@@ -0,0 +1,321 @@
+<?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 "documentation-guide.ent">
+%BOOK_ENTITIES;
+]>
+<section id="sect-workflow-patching" >
+ <title>Creating a patch</title>
+ <para>
+ Patches are files that show changes between two versions of a file. The patch file
can be shared via email or in a bug report, easily reviewed, and applied without requiring
additional manual editing. This section details the procedure for creating a patch for a
Fedora Guide.
+ </para>
+ <example>
+ <title>An example of a patch file</title>
+ <para>
+ A patch file might look like this one.
+ </para>
+ <para>
+ <![CDATA[From a6419e00b515765085cc4e646c3822ebdda607df Mon Sep 17 00:00:00 2001
+From: Pete Travis <immanetize(a)fedoraproject.org>
+Date: Mon, 30 Dec 2013 21:52:57 -0700
+Subject: [PATCH] Update commands for starting, stopping, and checking the
+ status of abrtd to use systemctl instead of service/chkconfig
+
+---
+ en-US/Automatic_Bug_Reporting_Tool_ABRT.xml | 20 ++++++++++----------
+ 1 file changed, 10 insertions(+), 10 deletions(-)
+
+diff --git a/en-US/Automatic_Bug_Reporting_Tool_ABRT.xml
b/en-US/Automatic_Bug_Reporting_Tool_ABRT.xml
+index 1093dc8..f01bb33 100644
+--- a/en-US/Automatic_Bug_Reporting_Tool_ABRT.xml
++++ b/en-US/Automatic_Bug_Reporting_Tool_ABRT.xml
+@@ -88,18 +88,18 @@
+ Your next step should be to verify that <systemitem
+ class="daemon">abrtd</systemitem> is running. The daemon is
typically configured to start up at boot time. You can use the following command as root
to verify its current status:
+ </para>
+- <screen>~]# <command>service abrtd status</command>
++ <screen>~]# <command>systemctl status abrtd</command>
+ abrtd (pid 1535) is running...</screen>
+ <para>
+- If the <command>service</command> command returns the
<computeroutput>abrt is stopped</computeroutput> message, the daemon is not
running. It can be started for the current session by entering this command:
++ If the <command>systemctl</command> command returns the
<computeroutput>Active: inactive (dead)</computeroutput> message, the daemon
is not running. It can be started for the current session by entering this command:
+ </para>
+- <screen>~]# <command>service abrtd start</command>
++ <screen>~]# <command>systemctl start abrtd </command>
+ Starting abrt daemon: [ OK ]</screen>
+ <para>
+- You can run the following <command>chkconfig</command> command to
ensure that the <systemitem
++ You can run the following <command>systemctl</command> command to
ensure that the <systemitem
+ class="daemon">abrtd</systemitem> service initializes every
time the system starts up:
+ </para>
+- <screen>~]# <command>chkconfig abrtd
on</command></screen>
++ <screen>~]# <command>systemctl enable abrtd
</command></screen>
+ <para>
+ Similarly, you can follow the same steps to check and configure the
<systemitem
+ class="service">abrt-ccpp</systemitem> service if you want
<application>ABRT</application> to catch C/C++ crashes. To set
<application>ABRT</application> to detect kernel oopses, use the same steps
for the <systemitem
+@@ -119,12 +119,12 @@ kernel.panic = 0</screen>
+ <para>
+ Finally, you can verify that the <systemitem
+ class="service">ABRT notification applet</systemitem> is
running:
+- </para>
+- <screen>~]$ <command>ps -el | grep abrt-applet</command>
++ </para>
++ <screen>~]$ <command>ps -el | grep abrt-applet</command>
+ 0 S 500 2036 1824 0 80 0 - 61604 poll_s ? 00:00:00
abrt-applet</screen>
+- <para>
+- If the <application>ABRT</application> notification applet is not
running, you can start it manually in your current desktop session by running the
<systemitem
+- class="service">abrt-applet</systemitem> program:
++ <para>
++ If the <application>ABRT</application> notification applet is not
running, you can start it manually in your current desktop session by running the
<systemitem
++ class="service">abrt-applet</systemitem> program:
+ </para>
+ <screen>~]$ <command>abrt-applet &</command>
+ [1] 2261</screen>
+--
+1.8.4.2
+]]>
+
+</para>
+ </example>
+ <para>
+ Let us examine how this patch file was created. In the following procedure, we will
create a patch to correct a line in the <citetitle>System Administrators
Guide</citetitle> to update from the legacy <command>service</command>
to the current <command>systemctl</command> command.
+ </para>
+ <procedure>
+ <title>Patch creation workflow</title>
+ <step>
+ <para>
+ First, find the guide you want to work on in the table at <ulink
url="https://fedoraproject.org/wiki/Docs_Project_guides_table" />.
+ </para>
+ </step>
+ <step>
+ <para>
+ The <literal>repo</literal> column of the table has a link to the
guide's git repository. Open the link, and you'll see the
<literal>Clone</literal> section at the bottom of the page, listing the
repository's URLs.
+ </para>
+ </step>
+ <step>
+ <para>
+ If you have set up ssh keys for your <ulink
url="https://admin.fedoraproject.org/accounts">FAS</ulink... account,
right click the URL that begins with <literal>ssh://</literal> and select
<guilabel>Copy Link Location</guilabel>.
+ </para>
+ <para>
+ If you have not set up ssh keys in FAS, or simply want to clone anonymously,
right click the url that begins with <literal>https://</literal> and select
<guilabel>Copy Link Location</guilabel>.
+ </para>
+ <para>
+ It is a good idea to use the <literal>ssh://</literal> url, even if
you do not currently have commit access. If you later gain commit access, you won't
have to go back and change the upstream location of the repo.
+ </para>
+ </step>
+ <step>
+ <para>
+ In a terminal window, change to the directory you have chosen to store guides in
and clone the repo. You can paste into the terminal window by right clicking it and
selecting <guilabel>Paste</guilabel>. Some terminal applications will also
paste with the key combination
<keycombo><keycap>Shift</keycap><keycap>Insert</keycap></keycombo>.
+ </para>
+ <screen>
+ <command>cd ~/fedora-docs</command>
+ <command>
+ git clone
ssh://git.fedorahosted.org/git/docs/system-administrators-guide.git
+ </command>
+ <command>cd system-administrators-guide</command>
+ </screen>
+ </step>
+ <step>
+ <para>
+ If you have already cloned the repo, it is important to make sure your local copy
is updated and matches the remote copy.
+ </para>
+ <para>
+ Pull in new changes from remote:
+ <screen>
+ <command>git pull</command>
+ </screen>
+ </para>
+ <para>
+ If you have made changes in the master branch that aren't committed, you can
<command>stash</command> them. The files will returned to the unchanged
state, and you can come back to them later. For detailed information, refer to
<command>man git-stash</command>.
+ <screen>
+ <command>git stash</command>
+ # continue with patch process, then bring back your stashed state with:
+ <command>git stash pop</command>
+ </screen>
+ </para>
+ <para>
+ If you have made <emphasis>and committed</emphasis> changes in the
master branch, you should push your changes:
+ <screen>
+ <command>git push</command>
+ </screen>
+ </para>
+ <para>
+ If you don't have access to push commits, or you don't want to push them,
you can reset your local copy to match remote:
+ <screen>
+ <command>git reset --hard origin/master</command>
+ </screen>
+ </para>
+ </step>
+ <step>
+ <para>
+ A new branch of the repository will allow you to make changes to the side,
without affecting the master branch until we are ready to. For smaller patches, this
branch is temporary and you won't have to share it. Name the branch something
recognizable to help you keep track of its purpose, then check out the branch.
+ <screen>
+ <command>git branch abrt-systemctl-not-service</command>
+ <command>git checkout abrt-systemctl-not-service</command>
+ </screen>
+ </para>
+ </step>
+ <step>
+ <para>
+ Find the files you need to change. A bug report might say "The abrt section
should use the systemctl command instead of service", but it will not tell you what
file or section to edit. In DocBook, commands are usually wrapped in the
<command> tag, so we can use that to help our search.
+ <screen>
+ <command>grep "<command>service"
en-US/*.xml</command>
+ <filename>en-US/Automatic_Bug_Reporting_Tool_ABRT.xml</filename>:
<screen>~]# <emphasis><command>service</emphasis>
abrtd status</command>
+ <filename>en-US/Automatic_Bug_Reporting_Tool_ABRT.xml</filename>:
If the
<emphasis><command>service</emphasis></command>
command returns the <computeroutput>abrt is
stopped</computeroutput> message, the daemon is not running. It can be
started for the current session by entering this command:
+ <filename>en-US/Automatic_Bug_Reporting_Tool_ABRT.xml</filename>:
<screen>~]# <emphasis><command>service</emphasis>
abrtd start</command>
+ </screen>
+ </para>
+ </step>
+ <step>
+ <para>
+ The <command>grep</command> command has found the file we want to
edit, <filename>en-US/Automatic_Bug_Reporting_Tool_ABRT.xml</filename>. Open
the file in your favorite editor and make the required changes:
+ <screen>
+ <command>vim
<filename>en-US/Automatic_Bug_Reporting_Tool_ABRT.xml</filename></command>
+ </screen>
+ or:
+ <screen>
+ <command>emacs
<filename>en-US/Automatic_Bug_Reporting_Tool_ABRT.xml</filename></command>
+ </screen>
+ or:
+ <screen>
+ <command>gedit
<filename>en-US/Automatic_Bug_Reporting_Tool_ABRT.xml</filename></command>
+ </screen>
+ </para>
+ <para>
+ The editor you choose is not important, but the file must be saved in plain text
format.
+ </para>
+ <para>
+ Change only the content you need to, so that the diff will be more readable.
Resist the temptation to rephrase passages unless they are misleading, to avoid making
more work for translators. Do not adjust sections to your preferred indentation depth;
this changes no actual content and makes the patch more difficult to interpret.
+ </para>
+ </step>
+ <step>
+ <para>
+ Test your changes by building the document, and reviewing the section in the
browser.
+ <screen>
+ <command>publican build --langs en-US --formats html</command>
+ <command>firefox tmp/en-US/html/index.html</command>
+ </screen>
+ </para>
+ </step>
+ <step>
+ <para>
+ After editing, if you want to check what files you have changed, use this
command:
+ <screen>
+ <command>git status</command>
+ <computeroutput>
+# On branch abrt-systemctl-not-service
+# Changes not staged for commit:
+# (use "git add <file>..." to update what will be committed)
+# (use "git checkout -- <file>..." to discard changes in
working directory)
+#
+# modified: en-US/Automatic_Bug_Reporting_Tool_ABRT.xml
+#
+no changes added to commit (use "git add" and/or "git commit -a")
+ </computeroutput>
+ </screen>
+ </para>
+ </step>
+ <step>
+ <para>
+ Commit your changes. If you only made a few changes, place them all in the same
commit. If you make many changes, edit different files, or work on varied issues, spread
your changes out into individual commits. This makes it easier for others to follow your
work.
+ <screen>
+ <command>git commit
en-US/Automatic_Bug_Reporting_Tool_ABRT.xml</command>
+ </screen>
+ </para>
+ <para>
+ After you run the command above, an editor will open for you to enter a commit
message. Be descriptive, explain what sections you have updated and why, and provide
references if available. If you are working on a specifig bug report, you should also cite
the bug in the commit message. something like <literal>RHBZ#439858</literal>
is enough but you can also cite the full URL if you prefer.
+ </para>
+ <note>
+ <title>Default Editor</title>
+ <para>
+ The default editor used by git is <application>vi</application>.
You can change this setting by adding a line in
<filename>~/.bashrc</filename>, such as:
+ <screen>
+ <command>export EDITOR="/usr/bin/emacs"</command>
+ </screen>
+ </para>
+ </note>
+ <para>
+ You can also bypass the editor and enter your message directly with the commit
command, like this:
+ <screen>
+ <command>
+ git commit en-US/Automatic_Bug_Reporting_Tool_ABRT.xml \
+ -m "Update commands for starting, stopping, and checking the status \
+ of abrtd to use systemctl instead of service/chkconfig"
+ </command>
+ </screen>
+ </para>
+ </step>
+ <step>
+ <para>
+ Check the status of your repository again, and make sure all the indended changes
have been committed.
+ <screen>
+ <command>git status</command>
+ <computeroutput>
+ # On branch abrt-systemctl-not-service
+ nothing to commit, working directory clean
+ </computeroutput>
+ </screen>
+ </para>
+ </step>
+ <step>
+ <para>
+ Now create your patches. Each commit will create one patch file, showing the
differences between your changes and the master branch.
+ <screen>
+ <command>git format-patch master</command>
+ <computeroutput>
+ 0001-Update-commands-for-starting-stopping-and-checking-t.patch
+ </computeroutput>
+ </screen>
+ </para>
+ </step>
+ <step>
+ <para>
+ Now that you've created the patch, share it! Attach it to the bug ticket,
send it to the mailing list, or share it with your mentor. The patch needs to get out for
review and inclusion in the master branch.
+ </para>
+ <para>
+ If there isn't an existing bug, you can create a new one. The patch created
when writing this section is attached to <ulink
url="https://bugzilla.redhat.com/show_bug.cgi?id=1047428" />
+ </para>
+ </step>
+ <step>
+ <para>
+ After you have shared your patch, you can clean up. Checking out the master branch
will return the files to the unedited state:
+ <screen>
+ <command>
+ git checkout master
+ </command>
+ </screen>
+ </para>
+ <para>
+ Clean any files that git is not tracking from the directory. This will delete
your patches, so make sure you have sent them off for review.
+ <screen>
+ <command>
+ git clean -xdf
+ </command>
+ </screen>
+ </para>
+ <para>
+ You can delete the local working branch as well. Again, make sure you have shared
your patches, or your work will be lost.
+ <screen>
+ <command>git branch -D abrt-systemctl-not-service</command>
+ <computeroutput>Deleted branch abrt-systemctl-not-service (was
a6419e0).</computeroutput>
+ </screen>
+ </para>
+ </step>
+ <step>
+ <para>
+ After review, the patch can be downloaded and then applied using
<application>git</application>:
+ <screen>
+ <command>git apply
0001-Update-commands-for-starting-stopping-and-checking-t.patch</command>
+ </screen>
+ </para>
+ </step>
+ </procedure>
+</section>
+
+
+
+
+
+
+
+
+
diff --git a/en-US/workflow.xml b/en-US/workflow.xml
index 0624dac..dc392a9 100644
--- a/en-US/workflow.xml
+++ b/en-US/workflow.xml
@@ -10,7 +10,10 @@
</para>
<section>
<title>Write First, Format Later</title>
- <para/>
+ <para/>
+ <para>
+
+ </para>
</section>
<section>
<title>Formatting in DocBook</title>
@@ -35,7 +38,9 @@
<section>
<title>Building Packages from Documents</title>
<para>Building packages from documents is discussed in <xref
linkend="sect-publican-packaging" />.</para>
- </section>
+ </section>
+ <!-- Section on creating a patch for a bug report or review -->
+ <xi:include
xmlns:xi="http://www.w3.org/2001/XInclude"
href="workflow-patching.xml"/>
</chapter>
<!--
Local variables: