preliminary guide to Mercurial via workflows

Thu Apr 30 09:44:09 CDT 2009

Am Mittwoch 29 April 2009 18:10:55 schrieb Martin Geisler:
> I think it's great that you've formulated these workflows! I think the
> second half of them are a little too advanced for an introduction, but
> they will work fine as, well, workflows :-)

I hope they get people going with the basic tasks while allowing for 
incremental learning. 

You only need the part your real workflow requires and can stop reading after 
that :) 

> > == Sysadmin workflow ==
> >
> > === Use Case ===
> >
> > The first workflow is also the easiest one: You're a sysadmin and you
> > want to use Mercurial to be able to look back when you did which
> > changes.
>
> I don't think this workflow is very sysadmin specific. When I saw the
> title I expected something about how to manage config files in /etc -- a
> way too advanced topic for a beginner's guide.

Would the name "log keeping" fit better? 

That's what it does, after all. 

> > [...]
> >
> > Note: The name doesn't mean that every sysadmin will only need this
> > simple workflow. It was chosen in honor of a [mail]() which reminded
> > us, that this simple usage is already a workflow in its own right.
>
> Such commentary should not be there, IMHO. If I want to learn how to use
> Mercurial I want simple precise instructions.

You're right - I took it out. 

> > ==== Add files and track them ====
> >
> > <code>$ cd project
> > $ (add files)
> > $ hg add </code>
>
> By the way, what kind of markup is this? I would suggest that we use
> restructuredText, if possible. It has some very nice features:

It's an evil mixture of pseudo-mediawiki syntax, plain text and html :) 

I have to convert the guide to html anyway, so I didn't really pay attention 
to the markup. Should have, though, to make it easier to review. 

Normally I use markdown for my stuff, since that looks best to me when read in 
a text editor :) 

> > [...]
> >
> > now an editor pops up and asks you for a commit message. Upon saving
> > and closing the editor, your changes have been stored by Mercurial.
>
> There should be something about configuring the username.

I'll have to think about how to add it in the flow of the text. 

> > == Lone developer with linear history ==
>
> I suggest using this scenario as base scenario.

I start with the simple logging, since I want to keep the new information in 
digestable hunks. 

First committing to the store, then updating from it, then sharing stuff. 

Adding the username to the first workflow will make it a bit bigger still, so 
I'd like to keep it at that. 

> > To start a new project, you initialize a repository, add your files
> > and commit whenever you finished a part of your work (atomic commits).
>
> "atomic commits" should either be explained or not be there.

I removed it. Thanks! 

> > [...]
> > 
> > $ hg serve
> >
> > Now all others can point their browsers to his IP address (i.e.
>
> use "e.g.," instead of "i.e.", or better "for example" or "which could
> be something like".

You're right, I should avoid shortcuts here. I now use "for example". 

> > 192.168.178.100) at port 8000. They will then see all his history
> > there and can sdecide if they want to pull his changes.
> >
> > [...]
> >
> > Often you won't have direct access to the repository of someone else,
> > be it because he's behind a restrictive firewall, or because you live
> > in different timezones. You might also want to keep your changes
> > confidential and prefer internal email (be sure to encrypt your emails
> > with GnuPG!).
>
> I don't think this is the place for GnuPG advertisements, even though I
> also use and like it :-)

I think it's important to add the info that internal mail without encryption 
isn't really that secure. And people who want their work to stay confidential 
should really use GnuPG in their workflows, so I think it fits there. 

> > Mercurial makes this easy for you by providing names branches. They
> > are a part of the main repository, so they are available to everyone
> > involved. At the same time, changes committed on a certain branch
> > don't get mixed into the changes in the default branch, so features
> > are kept seperate, until they get merged into the default branch.
>
> I thought the normal advice was to /not/ use named branches for feature
> development? The bookmarks extension could be mentioned instead.

I want to avoid using any extension in the introduction: It is intended to get 
people running with the core of Mercurial. The extensions then come into play 
for more advanced workflows. 

And I didn't know that Mercurial prompts to avoid named branches for features. 
CLones might be better for smaller features, but as soon as you want to 
collaborate on larger features, named branches are really useful (in my 
opinion). 

> It definitely practical, but I think large parts of it go way beyond
> what I would expect in an introduction.
>
> I think an introduction should show people the core principles of
> Mercurial. Explain people how to
>
> * add files
> * commit changes
> * remove files
> * rename files
>
> Doing that will lead to a string of commits. Then introduce the
> changeset graph:
> 
> ...

This sounds exactly like what we want to do for the Quick Start! 

Would you like to write it up as an article, so we can put it on mercurial-
scm.org as the Quick start? 

Best wishes, 
Arne

--- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- 
   - singing a part of the history of free software -
              http://infinite-hands.draketo.de
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 198 bytes
Desc: This is a digitally signed message part.
Url : http://selenic.com/pipermail/mercurial/attachments/20090430/e49310c3/attachment.pgp 