Skip to Content.
Sympa Menu

sm-discuss - Re: [SM-Discuss] git and usability

sm-discuss AT lists.ibiblio.org

Subject: Public SourceMage Discussion List

List archive

Chronological Thread  
  • From: Jeremy Blosser <jblosser-smgl AT firinn.org>
  • To: sm-discuss AT lists.ibiblio.org
  • Subject: Re: [SM-Discuss] git and usability
  • Date: Fri, 7 Jul 2006 16:45:37 -0500

On Jul 07, Andrew Stitt [afrayedknot AT thefrayedknot.armory.com] wrote:
> On Fri, Jul 07, 2006 at 09:50:11AM -0500, Jeremy Blosser wrote:
> > On Jul 06, seth AT swoolley.homeip.net [seth AT swoolley.homeip.net] wrote:
> > > I don't learn anything from a paste of commands. I need to know what
> > > those commands _do_. A paste of your insights doesn't let me know how
> > > you got them.
> >
> > The guide was written for people that just need a paste of commands to get
> > started. No nonsense, "I don't care about git I just want to get my work
> > done", "git for dummies", etc. It does that well enough to have gotten
> > some kudos from git users outside of our project. Again, if you want more
> > info, look the docs over and ask specific questions. There are also
> > various tutorials and such in the git docs, that's mostly what those of us
> > already doing fancy things with git have been using.
>
> I agree that we lack a document explaining git philosophy, it was
> exceedingly frustrating trying to figure it out for use with sorcery.
> I think that some regular git users would also like to see a deeper
> explaination. I've worked with people who try the pastes of commands and
> get burned because they dont do what they expect when applying them to new
> situations. To be honest I think the git guide already goes into too much
> detail on various scenarios that are of little interest to average gurus
> or confusing and not helpful to people who need to go outside of the
> examples.
> After you pass the basics, not understanding what the more advanced
> commands
> do just gets you in trouble. Git is powerful, and we need power, but it
> can be unforgiving if you dont understand what you're doing.

You may recall we didn't start out with the guide we have now, we started
out with a longer discussion of the deeper things behind the commands,
which ended up a mess. The problem is that not everyone wants the same
level of info. Some want just a dummies' howto that tells them what to
type in which situations, some want more description so they can derive
their own answers to new scenarios when they run into them. For the
former, having both available in one doc tends to confuse the heck out of
them (especially given a system as powerful as git), and this is what was
happening with the longer doc (though that one also had some accuracy
problems, which didn't help).

Anyway, we ended up with what we have now because it seemed to be what
worked for "the most people" to just get their stuff done using git. I'm
not that concerned with making everyone learn git itself since they're not
here to be git users, they're here to be smgl developers. (I'm not saying
anyone is asking we force everyone to learn git at some deep level, just
noting why I don't care as much about asking people to learn how to use
things as I might for something else.)

If what we have in that doc doesn't get us all we need then by all means we
should have other things that do. The main thing to keep in mind is that
different people are going to come at it different ways and one doc
probably won't do it for everyone. Yes, I know you're asking for multiple
docs, but even those individual docs are coming from a particular angle.

> I suggest the following:
>
> A really basic document that explains 1) basic cloning 2) commit 3) push
> 4) pull. No .git/remotes/origin shortcuts to "simplify" the push/pull

This one, for example, is hard because for quite a lot of people if you
give them a push/pull command that uses the full URL each time the first
question they ask is "how do I simpify that". I know the way this is
presented caused confusion for you but your approach wasn't typical based
on the other questions we were getting.

Some people just want a list of best practicies to have as little
interaction with $SCM as possible (and will run away in fear if they get
more than that), some want the base details so they can decide their own
best practices, some want both.

> commands, no branching, no cherry-picking, no checkouts, no nonsense,
> just the simple stuff someone who wants to update some spells would use.
>
> A document explaining rare but still relavent stuff for basic users,
> such as uncommitting local but not pushed changes, reverting changes
> that were pushed, reverting files in your tree, stuff like that.
> This shouldn't take up more than a screen of text in a web browser.
>
> A document that explains branching and fetch/pull/push mechanics, as
> in, what happens when you do each, the basic three stage flow of code
> (upstream master -> local origin -> local master -> (back to) upstream
> master).
> This would get into why its bad to checkout stable-0.X from the default
> clone and commit to it (which isn't really explained anywhere and the
> cause of much grief on my part).
>
> A document that has examples of other advanced stuff and assumes you've
> read the previous document, .git/remotes/origin shortcuts, how to make
> local branches for hacking on stuff, how to make remote branches for
> shared hacking on stuff.
>
> I think that would make it easier for new developers to get started but
> provide a sensible path for people to learn about and understand git
> when they're ready to advance.

The main difference I see here is that you're dividing up the different
sections of the existing doc on multiple pages and adding some more things
that could also be added to the existing doc. I don't really care if it's
one page or if someone wants to split it up into many, it probably should
be many but at the time I was just trying to get something in place that
could replace the one we had that was confusing people. Just keep in mind
the examples we have did come about organically as we found certain
approaches seemed to work better than others (for most people).

Attachment: pgpL2KmBAXmw3.pgp
Description: PGP signature




Archive powered by MHonArc 2.6.24.

Top of Page