[OH-Dev] Mid-month check-in: Sat 3/17, 4PM Eastern / 1 PM Pacific

[Asheesh Laroia]

Excerpts from Daniel Mizyrycki's message of Tue Mar 27 21:48:52 -0400 2012:
> I am replying inline a couple of emails here as they relate.
> 
> On 03/16/2012 11:24 PM, Pam Selle wrote:
> >  I want to work on this. Not right now, maybe not till next weekend,
> >  but I do :)
> Pam and everybody who'd like to move forward docs: There are a few wiki 
> documents that are already translated to ReST and indexed, so what needs 
> to be done is much easier now. Let's try to coordinate here for an IRC 
> discussion. Who is interested?

I'd show up (-:

I suggest that you pick one or two times and see who says they can come.

> >  On 03/15/2012 04:25 PM, Asheesh Laroia wrote:
> >
> >  Dear Devel folks,
> >
> >  <Exciting>
> >
> >  We have all this documentation hosted by readthedocs.org
> >  <http://readthedocs.org>. Meanwhile, we also have all these
> >  documentation pages hosted within the openhatch.org
> >  <http://openhatch.org> wiki.
> >
> >  Since readthedocs makes creating previous/next links, and
> >  subcategories, here is my thoughts for one good way to recategorize
> >  the docs we do have:
> .
> >  It would be super cool to merge these into the Sphinx docs.
> .
> >  <http://openhatch.readthedocs.org/>. These are generated from the rst
> >  files in docs/*. You can generate them locally, too -- see the
> >  docs/generate_html.py file.
> 
> As a proof of concept, I am the attaching a patch that add sphinx 
> indices to the existing docs in the repo. More about the pull request below.

*nod*

> On 03/22/2012 09:53 AM, Asheesh Laroia wrote:
> > > Some suggestions
> > >
> > > * Move all documentation to /docs and possibly have a symlink to
> > > docs (like README.rst) so they will be part of the official
> > > documentation. (One caveat is that Sphinx and ReadTheDocs work as
> > > expected as root for the documents is /docs, but github assumes
> > > root at the project level, so links to repo documents do not render
> > > correctly. We could point to ReadTheDocs to work around the issue,
> > > but this adds a dependency :( )
> >
> >  Oh, Github.
> >
> >  So the thing about symlinks is that they don't seem to work on
> >  Windows, even though git "supports" them, which leads to oddities. If
> >  you can test that adding a symlink is fine for people on Windows who
> >  clone the repo, that'd be great, but I remember problems before.
> Do we have Windows users for our repo? Are any of our developers working
> and supporting it?

Every once in a while we have Windows users for the repo. None of the most
active people are on Windows, but people show up at e.g. sprints with it.

> >  I see now that we did make README.rst a symlink; I'm curious what
> >  that does on Windows!
> Anybody with a Windows computer can answer, please?
> 
> >
> >  I would say yes, let's move all documentation to docs/, except leave
> >  a README.rst that simply says, "For documentation, look in the docs/
> >  directory."
> I am tempted to do this.

Yay

> >  As for Github linking, I would say let's make them work properly in
> >  Sphinx first, and see if we can get Github to fix its parsing of
> >  restructured text. In particular, I think their parsers for these
> >  text formats are actually on the web and freely licensed, so it would
> >  be quite possible to submit a pull request to them.
> I think the issue is that a /README is very well accepted for package 
> distribution.

Huh?

> > > * Add an authors.rst or/and contributors.rst file on the repo.
> >
> >  I like this idea. I'd say contributors.rst but whatever's most common
> >  in rST-land.
> I'll do some surveys on this.

Awesome! Also, feel free to just pick one randomly.

> > > Some people have shown interest to help with docs. How would you
> > > like we move forward?
> >
> >  I would say:
> >
> >  * Discuss docs-related ideas on the mailing list and/or IRC
> following up :-)
> 
> >
> >  * Submit patches (with git format-patch, either to the mailing list
> >  or a ticket) or pull requests (on Github.com)
> proof of concept attached.
> 
> >  Given what we've seen so far, probably you'll prefer the Github pull
> >  request route.
> Yes

Cool. (:

> >  I'll rebase those to be against current origin/master,
> >  sanity-check, and push!
> Nice. I've got an issue though. I forked oh-mainline and before my 
> previous pull
> request I did "git pull --rebase upstream master" so my commits get 
> added to the end
> of the history, and keep master history linear. After the pull request 
> got merged, plus some other commits, I tried to  "git pull --rebase 
> upstream master" (this went well) and "git push" (back to my fork and got:
> To git at github.com:mzdaniel/oh-mainline.git
>   ! [rejected]        master -> master (non-fast-forward)
> error: failed to push some refs to 'git at github.com:mzdaniel/oh-mainline.git'
> 
> After doing gitk, found that the history of oh-mainline is not linear. 
> Any quick reference to a howto I can look at to push my changes for a 
> proper pull request?

Once you have rebased your changes to be on top of origin/master , create a
new branch on your personal github fork, and then use the github.com functionality
to request your branch be merged into openhatch/oh-mainline:master .

I am not an experienced Github.com users, but I do have experience with Git itself.

Here's what I suggest as a workflow. You've already done much of this, but for new
people I wanted to lay it all out.

* In Github.com, create a 'fork' of the OpenHatch project

* On your machine, use 'git clone' to clone from that fork. Now 'origin' is your
  writable Github fork.

* Create a remote called openhatch that points at the official repo

   git remote add openhatch git://github.com/openhatch/oh-mainline.git
   git fetch openhatch

* On your local machine, make the 'master' branch point to openhatch/oh-mainline:master

   git checkout master
   git fetch openhatch
   git rebase openhatch/master

* Periodically, use 'git fetch openhatch && git checkout master && git rebase openhatch/master'
  to keep that in sync

* As you work, create local feature branches:

   git checkout openhatch/master -b my_feature_branch

* Make changes, and make local commits

* If you're ready for casual review, just push that branch to your Github account

   git push origin my_feature_branch

* If you're ready for formal review, make sure it's rebased on top of latest
  openhatch/master and push (maybe requiring --force so take care)

   git fetch openhatch
   git rebase openhatch/master
   git push origin my_feature_branch
   # Note: You might need to do:
   # git push --force origin my_feature_branch
   # if the 'git push' complains about the non-fast-forward
   # that you saw above.

* In Github.com request that openhatch/oh-mainline:master pull from you!

> >  Does that seem like a usable workflow?
> Yes. You mention creating a docs branch at some point. Do you still 
> think is a good idea?
> If yes, I am assuming that branch will be created in my fork and 
> somebody will merge
> it to master. Then, I just need to rebase my fork and recreate the doc 
> branch for new
> changes.

Yup, precisely. See above, and I+others can also help out more on IRC or the
list.

In your case, you need to just make sure that you do a force push before you
use the Github.com interface to do the pull request.

-- Asheesh.