Re: [Pyblosxom-devel] status: June 12th, 2011

[seanh <sn...@gm...>]

On Sun, Jun 12, 2011 at 10:24:21PM -0400, will kahn-greene wrote:
> I've overhauled the development docs accordingly:
> 
>     http://pyblosxom.bluesock.org/static/development.html
> 
> They assume you have a working knowledge of git currently.  I plan to 
> add links on how to learn git, but really don't want to host our own git 
> tutorial.  With that in mind, does the changes in the documentation make 
> sense?  Are they still hard to follow?  What specific changes would you 
> make?

I think the instructions on that page are clear and useful.
I'm fairly experienced with using git by myself and have only a little
experience with using git to collaborate with others (some of what I
know about collaboration I learned by submitting contributions to the
pyblosxom docs). For me the instructions on that page are at a
reasonable level of detail and are useful. I messed up at first by not
using bugfix branches, these instructions would have prevented that.

The main git website at http://git-scm.com/ has good links on how to
learn git, maybe the pyblosxom site only needs one link to that site.

I think the page could do with a sentence in the introductory section
that says something like "The pyblosxom project uses
[git](http://git-scm.com) for version-control and collaboration, and our
git repositories are hosted on
[gitorious](http://gitorious.org/pyblosxom/)." Currently the first you
hear about git is when you see the git clone command in the
instructions.  It actually took me a while to locate a link to the
gitorious project page.

It's also might be worth explicitly mentioning that people can create a
free account on gitorious and host their own fork of pyblosxom in order
to collaborate with us. This is sort of mentioned under "How to send us
your changes" but I think it could be more explicit about the fact that
using gitorious for this is free.

Typo (missing word): "what our coding conventions (or should be)"