Docs Development Workflow: Am I Barking Up The Right Tree?

[John Ralls]

> On Feb 24, 2016, at 5:27 PM, David T. <sunfish62 at yahoo.com> wrote:
> 
> Hey all,
> 
> I’m ba-ack!!!
> 
> Having set aside work on documentation for a while, I thought I’d try to implement some of the documentation suggestions that have come up on the lists recently. As Geert and Frank know, I ran into some troubles when I looked at my outdated local Git repository. The quick fix was to nuke the whole thing and start over.* 
> 
> With a fresh fork on GitHub and a new SourceTree repository, I decided to take on a simple documentation edit: Bug 762088, which is a request (by me, as it turns out) to remove a small section from the Guide. I will throw myself on the mercy of the list to check whether I have proceeded appropriately into the Git Forest. Here are the steps I have taken:
> 
> 1) I noticed that SourceTree was pointing at master, and somewhere in my brain I recalled something about making my changes to maint, so I changed SourceTree to use maint. 
> 
> 2) I created a new branch for work on the bug, which I famously called “bug-762088”.
> 
> 3) I called up ch_capgain.xml in Xcode, made the edits, and saved the file.
> 
> 4) I told SourceTree to commit the changes and issue a pull request.

So far so good. There's one more step you should do before committing: configure and run make && make check. Make check will run some XML checks to make sure your change complies with the DocBook DTD. After running make you'll have an HTML version of the doc with your changes which you can review in your browser which is a bit friendlier for proof-reading. The instructions are on the wiki Documentation page; I'll repeat them here for your convenience:

mkdir build 
cd build
../configure 
make
make check

To view e.g. the guide in your browser, type in the following URL. It assumes that you put gnucash-docs in your user directory and that you made your user "sunfish42". Adjust as necessary and notice the 3 slashes after file:

file:///Users/sunfish42/gnucash-docs/build/guide/C/html/index.html

BTW, Xcode has git integration built in, so you might want to experiment with using that instead of SourceTree. They're both graphical front ends to the same git code, so you can flip back and forth at your whim with no harm to your repository.

> 
> My points of doubt:
> 
> A) Is this how it is supposed to go? When I look on Github, I see an open Pull Request on my repository that says I have requested to merge this into maint. I think that’s what it’s supposed to be, but I don’t know for sure.

Yup, the PR showed up in my email. I'll review it soon.
> 
> B) What happens next? Does someone in the development group act on this? Where will this next action appear? Github? Gnucash-devel? Bugzilla?

Any comments on the PR itself will be on the "Conversation" tab of the PR page and if you set up Github to email you you'll get them in your email. 

> 
> C) Do I do something on bugzilla?

It would be nice to add a comment to the bug pointing at the PR.

> 
> D) If the GnuCash Politburo approves my commit, what do I have to do on my end to ensure that my Forking copy is up to date, and that I am seeing the most current version of the documentation? The Scorched Earth method is already old.

Once you have a fork on Github synchronization is manual: You have to pull from upstream and push back to your github repo in your local repo. If you followed the wiki Git page suggestion, the commands would be

  git pull --rebase upstream
  git push origin

You need to do that in both maint and master branches if you want to keep both synched, but there's no reason to keep master synched if you don't want to, you'll be working only with maint. 

The --rebase argument to the pull command rebases any local changes you've committed on that branch so that they're after the latest upstream commit. It will be less work for you if you keep all of your own changes on feature branches and don't merge those yourself into maint; the developer handling the PR might have to rebase your feature branch if there have been commits to maint since you made it or do a simple fix for you and that would make your merge conflict with his. That's not hard to clean up from, but the cleanup is extra work. Following that rule (about keeping your own work on feature branches) also makes the --rebase flag unnecessary.

Once a feature branch has been merged you'll want to delete it:

   git branch -d bug-xxxxxxx

will work after your PR has been merged as long as the feature branch didn't have to be rebased or changed. Otherwise you need to force-delete the branch:

   git branch -D bug-xxxxxxx

To delete the branch from your github repo:

   git push origin :bug-xxxxxxxx

Note the colon. That's telling git to replace the remote branch with nil.

> 
> E) If I am looking to keep working on other documentation bugs, what should I do next? Do I repeat steps 2-4 above? What kinks am I going to encounter if I’m not careful?

Yes. The main "kink" will be that you need to rebase your feature branches on top of maint
  git rebase maint bug-xxxxxxx
before submitting.

 
> 
> TIA,
> David
> 
> * I will note that my current state of the art is to follow this procedure. I know that this is not the most efficient method, but…

See above about pulling from upstream and pushing to your repo.