Preparing A Documentation Patch
Contents
Preparing A Documentation Patch
When preparing documentation updates, you might choose to create and upload a patch to Bugzilla. Here are directions for correctly preparing a documentation patch.
Ensure your Local Copy of the Repository is the Same as on Github
A patch should always be made against the most recent revision of the gnucash-docs project in github, so the next step is to get the latest version and re-apply your changes to it:
git pull --rebase
Most of the time this will work with no changes needed, but if someone else has committed a change in the same files that you did you'll get conflicts.
Conflict Resolution
git status will tell you which files have conflicts, and when you open one of them it will be marked with lines like
<<<<<<HEAD ... ====== ... >>>>>>Your change summary
You'll have to edit each file with conflicts to remove those lines and get the section in between to read the way you want. After you've fixed up a file, use git add path/to/filename to register the changes and when you've fixed them all and added them to the index, use git commit to re-commit them. This time in the editor you'll see a line
Conflicts:
followed by a list of the files with conflicts. Be sure to remove those lines from the file, since you've resolved the conflicts.
There are other tools that can simplify cleaning up conflicted files, but they're beyond the scope of this tutorial.
After resolving your conflicts and recommitting, it's wise to re-do steps 8 - 10 to make sure that everything wound up the way you want it.
Prepare your Patch
Once everything is tested and committed, and you're confident that your changes are correct, you're ready to make a patch. A patch file needs to be created for each commit. Each patch file will be named '0001-<your-summary>', substituting the first line from your commit message for <your-summary>, with spaces replaced by hyphens. For example, if one of your commits had a summary "Better explanation of trading accounts", the corresponding patch file name would be 0001-Better-explanation-of-trading-accounts.patch.
Check how many commits you have made with
git status
You can make patches, 1 for each commit, for all commits which are in the current branch but not in the origin branch, with
git format-patch origin
Or if you have done only 1 commit, create a patch from your latest commit with
git format-patch HEAD^
Or if you have done more than 1 commit, create a patch file for each commit with
git format-patch -n
where n is the number of commits for which patches should be created.
Attach Patch to Bug
Attach your patch file(s) to a GnuCash bug report and you're done! The relevant people will be automatically notified by email.
