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: Andrew Stitt <afrayedknot AT thefrayedknot.armory.com>
  • To: sm-discuss AT lists.ibiblio.org
  • Subject: Re: [SM-Discuss] git and usability
  • Date: Fri, 7 Jul 2006 10:04:15 -0700

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:
<snip>
> > 4) since git is so space efficient, git should be supported as a
> > first-class download utility for the grimoire so that we can drop rsync
> > and the convoluted hashsum scheme we have (although is there any way to
> > use a hash other than sha1 in git? -- if not that seems like a major
> > oversight.
>
> I'm pretty sure this is planned for after we actually officially are using
> git for good. We aren't yet.
>

Thanks to dmlb2000, test and devel sorcery both have support for
downloading with git. I dont know how well tested scribe is, but it
should work (and if not we will fix it). As a general goal, the sorcery
team intends to support downloading the grimoire via whatever scm the
grimoire team uses. We're ahead of the curve on git because the handler
was already written, I think for use with the linux spell. We do intend
to get away from rsync and use something a little more self-managing.

<snip>

> > 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.

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
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.

-Andrew


--
_________________________________________________________________________
| Andrew D. Stitt | acedit at armory.com | astitt at sourcemage.org |
| irc: afrayedknot | Sorcery Team Lead | ftp://t.armory.com/ |
| 1024D/D39B096C | 76E4 728A 04EE 62B2 A09A 96D7 4D9E 239B D39B 096C |
-------------------------------------------------------------------------




Archive powered by MHonArc 2.6.24.

Top of Page