[documentation-guide] added workflow SOP for creating a patch with git
Pete Travis
immanetize at fedoraproject.org
Tue Dec 31 07:33:17 UTC 2013
commit 0b1847f4f8728f598d81285b0ccdf5d88282c70c
Author: Pete Travis <immanetize at 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 at 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:
More information about the docs-commits
mailing list