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 09:50:11 -0500

On Jul 06, seth AT swoolley.homeip.net [seth AT swoolley.homeip.net] wrote:
> As a real test for git, I'd like to get proficient at using Git as
> powerfully as I used perforce.
>
> I think we need to really work on the git guide:
>
> http://wiki.sourcemage.org/Git_Guide
>
> It doesn't cover my normal use cases at all.

It's meant to primarily cover the basic cases for most people that just
need to do basic spell updates. If it gets very detailed on other stuff it
will be harder for people to find the easy stuff and they'll be scared of
using git. The perforce wiki pages we had were not much different in
scope. If we need to document more complex things it should be on
subpages.

A lot of the rest of these aren't actually git issues, they're process
things we'd probably have regardless...

> 1) for example, cherry picking covers doing an entire file or a single
> change, but not our normal case, how do I "cherry pick" an entire
> spell/directory?

You don't. This was discussed in a fair bit of depth when we were
originally looking at SCMs, since a lot of them have gotten more anal about
this. I'm not going to rehash the arguments for or against, been there
done that.

If you really need to merge just a specific set of files you can fake it a
couple ways in git using temp branches or the patch facilities.

> 2) we need an "integrate" script that properly checks that grimoire
> functions get pulled up and gpg keys are validated upon integrate, and
> any other inherited files don't conflict under the new inheritance
> scheme. This could all be scripted up and we could maintain these tools
> for ease of distribution work. It could even warn of potential
> dependency mismatches with versions and generate a test list of spells
> to test.

Not a git issue but feel free to write something.

> 3) I don't know how to release the stable grimoire without Arwed's
> modifications to my scripts, which were modifications of previous
> scripts, etc, etc. This should be documented somewhere.

Not a git issue, but yes.

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

> 4a) in a related vein, perhaps we need to make "release" branches such
> as stable-rc-release and stable-release that are the live, "this is what
> is published" branches. That would allow us to submit directly into
> stable, delay release while final testing happens (mostly automated --
> for security update and integrate sanity) and then ship the bits to
> stable-release, where there's a trigger to actually tarball up the
> trees.

Also not a git issue; I think Arwed was most interested in just naming the
branches eg '0.4' and then tagging it when it was released as stable.

> 5) Does anybody know of any _good_ documentation on git. The git
> documentation is mostly "command docs" and a general philosophy. I need
> a "general use case" or "best practices" guide. It's perhaps too
> flexible for me to decide which way to do things.

You can ask #git most anything and get a straight answer. The thing to
keep in mind is that git was largely written as the "internal guts" code,
with assumption other things would be written as interfaces for humans to
actually use, and the docs reflect this. Now that git is including more
front end commands directly they know they need to update the docs and are
putting a lot of time into that but it's not done yet. They're very
interested in feedback on this kind of thing, though.

Our guide is working toward "best practices" as we figure them out, but at
a pretty high level.

> 6) And lastly, I would like to branch versions of the grimoire out and
> delete branches later. The reason for this is that I'd like to maintain
> security updates for older stable branches at least going back six
> months. I think that amount of time is required for deployment in a
> corporate environment. I'm not and we aren't necessarily the people to
> do this maintaining, but if we store them back that far, at least others
> can help maintain them and we can host the bits for their efforts. The
> alternative is simply to rename the branches to the new version and
> overwrite them (or delete the old branches very quickly -- I have no
> idea which way is "better" in git philosophy, for example --
> again there's no "best practices" document).

I'm not sure what the question is here.

a) There's nothing preventing anyone from branching grimoire versions out
or deleting them later (you can't yet delete remote branches but people
managing stable* branches won't have a problem getting this done either on
the server themselves or asking for it).
b) Speaking from a corporate environment, it's less likely people will need
anyone to maintain security updates against a given branch of stable than
it is they'll need an older version of something that was in a previous
version of stable. Regardless, see bug 11809.
c) Really not sure what you're talking about with renaming. In any case
git's not going to care what we do with our branches, one of its core
features is flexible branches to do most anything.

> 7) cherry picking has a different strategy for local branches and remote
> branches in the git guide? Why?

You can currently only use the cherry-pick command on local branches. If
you already have the branches you need locally this is easy. If you don't
you can deal with it multiple ways, the one documented there is to bring
the remote branch down as a temp local branch so you can still use
cherry-pick.

> Can we get those merged and explained step-by-step?

The only other sane way to document them that would count as "merged" would
be to have step 0 be "get the dest branch locally if it isn't already" and
I'm not going to document it that way there and have it confuse the people who
think they have to do things to already local branches. If you want "why"
info you'll be served best just reading the man pages for the referenced
commands and asking specific questions if you have them.

> 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 started out writing things as "best practices and how I got there" but in
the end it confused people more than anything so I abbreviated down to
"just the facts" since that's what most wanted.

> It's late, I've been planning on getting a stable update out now for a
> couple weeks but have been too busy with scheduled events. I don't
> think only Arwed and I should be responsible for releasing an approved
> release if both of us are busy, we need to have a documented process...

I'm going to note that every time someone asked on IRC "when is stable"
the response was some date in the near future, never "can someone else look
at it". I could have done it most times, Andrew probably could have too.
We need a documented process less than we need communication of whether
people really have time or not or need some help. That's not a statement
of blame, I'm just saying: I don't think we lacked people interested in
helping, we did lack anyone indicating they needed help, and we're not
going to be inclined to walk in and take it.

> granted, neither of us have done a full release on git before, and
> that's slowing us down (at least me) -- it's a totally new process.
> I'll have tons of time this weekend to get it done, but if somebody can
> go through and answer some of my questions and rework the git guide a
> bit, I'd much appreciate it.

Attachment: pgpW5PHSae8Tk.pgp
Description: PGP signature




Archive powered by MHonArc 2.6.24.

Top of Page