Procedure 3.1. Patch creation workflow

1. First, find the guide you want to work on in the table at https://fedoraproject.org/wiki/Docs_Project_guides_table.
2. The repo column of the table has a link to the guide's git repository. Open the link, and you'll see the Clone section at the bottom of the page, listing the repository's URLs.
3. If you have set up ssh keys for your FAS account, right click the URL that begins with ssh:// and select Copy Link Location.
   If you have not set up ssh keys in FAS, or simply want to clone anonymously, right click the url that begins with https:// and select Copy Link Location.
   It is a good idea to use the ssh:// 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.
4. 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 Paste. Some terminal applications will also paste with the key combination Shift+Insert.

           cd ~/fedora-docs
            git clone ssh://git.fedorahosted.org/git/docs/system-administrators-guide.git 
           cd system-administrators-guide
   

5. If you have already cloned the repo, it is important to make sure your local copy is updated and matches the remote copy.
   Pull in new changes from remote:

             git pull
   

   If you have made changes in the master branch that aren't committed, you can stash them. The files will returned to the unchanged state, and you can come back to them later. For detailed information, refer to man git-stash.

             git stash
             # continue with patch process, then bring back your stashed state with:
             git stash pop
   

   If you have made and committed changes in the master branch, you should push your changes:

             git push
   

   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:

             git reset --hard origin/master
   

6. 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.

             git branch abrt-systemctl-not-service
             git checkout abrt-systemctl-not-service
   

7. 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.

             grep "<command>service" en-US/*.xml
             en-US/Automatic_Bug_Reporting_Tool_ABRT.xml:    <screen>~]# <command>service abrtd status</command>
               en-US/Automatic_Bug_Reporting_Tool_ABRT.xml:      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:
               en-US/Automatic_Bug_Reporting_Tool_ABRT.xml:    <screen>~]# <command>service abrtd start</command>
   

8. The grep command has found the file we want to edit, en-US/Automatic_Bug_Reporting_Tool_ABRT.xml. Open the file in your favorite editor and make the required changes:

             vim en-US/Automatic_Bug_Reporting_Tool_ABRT.xml
   

   or:

             emacs en-US/Automatic_Bug_Reporting_Tool_ABRT.xml
   

   or:

             gedit en-US/Automatic_Bug_Reporting_Tool_ABRT.xml
   

   The editor you choose is not important, but the file must be saved in plain text format.
   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.
9. Test your changes by building the document, and reviewing the section in the browser.

             publican build --langs en-US --formats html
             firefox tmp/en-US/html/index.html
   

10. After editing, if you want to check what files you have changed, use this command:

              git status
               # 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") 
    

11. 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.

              git commit en-US/Automatic_Bug_Reporting_Tool_ABRT.xml
    

    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 RHBZ#439858 is enough but you can also cite the full URL if you prefer.

    Default Editor

    The default editor used by git is vi. You can change this setting by adding a line in ~/.bashrc, such as:

                export EDITOR="/usr/bin/emacs"
    

    You can also bypass the editor and enter your message directly with the commit command, like this:

               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" 
    

12. Check the status of your repository again, and make sure all the indended changes have been committed.

              git status
               # On branch abrt-systemctl-not-service nothing to commit, working directory clean 
    

13. Now create your patches. Each commit will create one patch file, showing the differences between your changes and the master branch.

              git format-patch master
               0001-Update-commands-for-starting-stopping-and-checking-t.patch 
    

14. 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.
    If there isn't an existing bug, you can create a new one. The patch created when writing this section is attached to https://bugzilla.redhat.com/show_bug.cgi?id=1047428
15. After you have shared your patch, you can clean up. Checking out the master branch will return the files to the unedited state:

             git checkout master 
    

    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.

               git clean -xdf 
    

    You can delete the local working branch as well. Again, make sure you have shared your patches, or your work will be lost.

              git branch -D abrt-systemctl-not-service
              Deleted branch abrt-systemctl-not-service (was a6419e0).
    

16. After review, the patch can be downloaded and then applied using git:

              git apply 0001-Update-commands-for-starting-stopping-and-checking-t.patch