Adam Tuttle

How you can contribute to Taffy documentation

I've had more than one person offer to help me with Taffy documentation lately, and I would love to be able to open it up just like the source code of the project so that people could make proposed changes and submit a pull request. Unfortunately this is a standing request that's yet to be filled for Github Wiki's.

I think I may have found a workaround.

It takes a little bit of extra effort (only a little!) and I would only recommend it for intermediate gitter's and above. (Sorry noobs!)

Every wiki should be available as a git repo already. For example, you can see Taffy's here, and FW/1's here.

My proposed workflow is this:

  1. Manually create a fork of the Taffy wiki on your Github account:
    • Create a new repository on your github account. Let's call it "Taffy-Wiki".
    • Clone the Taffy wiki repo to your local machine somewhere:
      git clone git://github.com/atuttle/Taffy.wiki.git
    • Remove the original "origin" remote and add your github repo as new "origin"
      git remote rm origin and
      git remote add origin git://github.com/<YOUR_USERNAME>/Taffy-Wiki.git
  2. Make your proposed changes locally, then push them to your github account:
    git push -u origin master
    ('-u origin master' only required the first time; afterwards just do git push)
  3. Submit a ticket to the official Taffy issue tracker requesting me to review your changes and merge them in. Please be sure to include a link to your repo and describe what you've changed.
  4. Goto #2

I apologize if that sounds complicated, but when you think about it in comparison to making code changes and submitting a pull request, it's not that much more complex. Also, here's a script you can copy/paste into your terminal that will do the forking for you, except the repo creation:

git clone git://github.com/atuttle/Taffy.wiki.git; cd Taffy.wiki; git remote rm origin; git remote add origin git://github.com/<YOUR_USERNAME>/Taffy-Wiki.git

This requires that you:

  • First create a new Github repo named "Taffy-Wiki"
  • Insert your github username for <YOUR_USERNAME> toward the end

This way anyone can submit documentation patches and I'll be able to review easily merge them in and keep the published wiki updated. (I had considered just putting the wiki source in to a folder or branch of the source repo, or its own repo, but that comes with its own challenges like keeping the published wiki updated.)

Thanks for your interest and contributions!

4 responses:

Adam

Adam

Woohoo! This post was originally inspired by the lack of pull-request support for wikis on GitHub, and while I'd love to be able to report that they've decided to add PR's to wikis, that is not the case.

The good news is that a GitHub employee commented on the feature request[1] and said that my approach, outlined in this post, seemed like the best possible workflow at the moment.

That doesn't improve anything, but at least it validates my decision and proves I'm not entirely crazy. :)

[1]:https://github.com/github/gollum/issues/265#issuecomment-5529605
drio

drio

Hi Adam,

How do you merge the changes into the actual project wiki once you have reviewed them?

-drd
Ken Williams

Ken Williams

To change the origin URL, you can just do this:

git remote set-url origin git://github.com/<YOUR_USERNAME>/Taffy-Wiki.git

And then you won't need to add the '-u origin master' arguments to 'git push' the first time either.
Larry Botha

Larry Botha

I've put together a gist on how to merge wiki changes made on forked repos: https://gist.github.com/larrybotha/10650410

It explains how this can be managed for both the forker, repo owner, and also removes the need for the forker to create a dedicated wiki repo if they have done a full fork.

I found this article a little ambiguous as to what was happening in which repo, and then how to even merge changes once there is an update on a fork.

Your comment:

Leave this field empty: