Can't commit any changes?

[Paul Boddie]

Ray Bartlett wrote:
> Yes, I've spent almost a week combing the web for information about
> what Mercurial is and isn't, what it can and can't do, and I have to
> say that compared to a lot of open source products out there,
> Mercurial documentation isn't really aimed at someone coming in new.
>   

I think I agree with you there in the sense that much of the 
documentation doesn't really try to make the case for version control: 
it assumes that you either know what it is, or that you know it is a 
desirable thing. Historically, there was a need to make the case for 
using Mercurial (or any other tool) in preference to other tools in 
common use, either making the case for distributed version control 
itself, or making the case for Mercurial (or another tool) in comparison 
to its direct peers, and thus a lot of the documentation addresses an 
audience who is already informed to a certain level and mostly needs 
persuading that they are making the right technology choice.

> There's not a link in this thread that I haven't already seen, tried,
> and either understood or didn't.  I see a lot of comparisons written
> for people who already know Subversion about how Mercurial is
> different and so on.  But some of the documentation is actually quite
> confusing for someone who hasn't used version control to begin with.
> It would be nice to have a better sense not of workflows (which never
> quite seem to fit what people are trying to do) and rather the pieces.
>   

It's interesting that many introductory guides talk about cloning before 
making a new repository. I would imagine that working with existing 
projects is the first experience of a tool like Mercurial for many 
users: they need to work on some open source project using "this 
Mercurial thing" and therefore need to know the basics of getting the 
code, changing it, committing, pushing, and so on, with all the 
infrastructure taken care of.

>  I.E.  "To use Mercurial, you need three things:  a repository, a
> .hg/hgrc file, and a clone.  The repository is the original source,
> the clone is where the changes are made..." etc.
>   

An .hgrc file, surely? But yes, maybe you've highlighted a genre of 
documentation that needs writing.

> Take the http://mercurial.selenic.com/wiki/SharedSSH page, for
> example.  It's not a page that steps someone through the process of
> setting this up.  It's just a listing of different elements that
> relate to SharedSSH.  The same with many of the Tutorials I've seen.
> The quick start, followed to the letter, didn't mention anything about
> setting up a proper .hg/hgrc file, which is apparently vital.  Then
> when running Mercurial, I got an error (not mentioned in the Quick
> Start) that turns out to be because I have to add a username to the
> .hg/hgrc file (as in [ui] username = me <foo at foo.com>).  But it still
> didn't work.
>   

I think you might be experiencing confusion about .hgrc versus .hg/hgrc 
files, but this actually illustrates a point about writing 
documentation: it can be very difficult to find the right level when 
writing about even the most basic things. I noticed that on one page, 
there's a mention of "~/.hgrc" whereas another refers to ".hgrc in your 
home directory". Neither is wrong, but both assume a certain level of 
knowledge that the casual reader may not have. Additionally, .hgrc and 
.hg/hgrc are confusingly similar both in terms of naming and in terms of 
their purpose. Still, it would be tiresome to have to spell everything 
out every time .hgrc files were mentioned, and I suppose that better 
linking to common resources would pay dividends.

As for SharedSSH, it's more or less a reference page. Of course, this 
means that there might be a need for a different style of page to 
describe why you would need to use those tools. In your case, I imagine 
that SharedSSH is a distraction: your developers probably have real 
accounts on the Linux server and can use "normal SSH" mechanisms to log 
in or connect.

> It's not like I haven't found these resources on the web or haven't
> read them.  It's that they seem to start with workflow scenarios and
> examples with X wants to do this with Y, then he wants to do this,
> then that, scenario by scenario, without any discussion of why things
> won't work or cautions or what should or shouldn't be in the .hg file
> and so on.  I have 2 people who really want to use the GUI tool Hg,
> too, because they don't like the command line (their fault, not yours,
> sure, but it's the way Mac users are...) and so the examples don't
> really connect to the scenario I'm seeing.
>   

I agree that workflow descriptions can be quite good at polarising the 
audience into those who find them startlingly similar to what they want 
to do, and those who cannot identify with them whatsoever.

> Am I right to understand that without a line in the .hg/hgrc file
> specifying a path, no changes will ever get back to the central repo?
>   

No. In many of my working directories, I don't even have a .hg/hgrc 
file, but that means that I do need to push to an explicit location. For 
example:

hg push ~/hg/myproject
hg push https://someserver/myproject
hg push ssh://me@myserver/hg/myproject

> And am I right to understand that while yes, Mercurial doesn't have a
> "central" repo, since we need one, we can achieve something similar by
> having people clone from and push to the same place, so that each time
> someone's cloning it's always the latest version?
>   

Yes. With a system like Mercurial, you can nominate a repository to be 
the "central" one, through which all users push their changes and pull 
updates.

> In our case, Person A works on project foo Monday and Tuesday.  On
> Monday morning, he logs into his local machine, then clones the
> project that's on our web root Linux dev server:
> /var/www/html/lasersharks.  Since everyone knows he's working on the
> project until Tuesday, nobody else clones it.
>   

I think that the /var/www stuff confused a few people about how you were 
trying to publish the repositories, but in effect what you're saying is 
that each project is a live Web site that people can look at to verify 
whether it is OK or not, and that each project exists as a central 
repository that is accessed by the developers. How you publish those 
files is a separate matter from serving it as a Web site: you can have 
your users clone the files via ssh (if they have accounts on that 
machine, or using some kind of thing described by SharedSSH), or they 
could clone the files via hgweb (which is a Web serving solution that 
would need to be set up to serve the files as actual files, not as Web 
content, such that stuff like PHP files, for example, appear as the 
actual PHP source and not the generated Web content that the PHP 
evaluates to).

It actually doesn't matter whether other people clone the project or 
not, by the way. No-one actually locks the project to prevent other 
people from working on it.

> He works with lasersharks for Monday and Tuesday, and then pushes it
> back to the /var/www/html/lasersharks location.  Presumably, his local
> copy and the one in ...lasersharks will be identical.
>   

For the purposes of this discussion (and to ignore anything I might not 
have considered), yes.

> On Wednesday, he knows Person B will be doing something with the
> project.  She clones it from /var/www/html/lasersharks and works with
> it for half a day.  When she's done, she pushes to the dev server.
> Because it's on the dev server, anyone in the intranet can easily see
> the project and offer comments or suggestions.  If it's on their local
> machine, we'd have to get up and walk over to their desk to see
> changes.
>   

Correct.

> On Thursday, it's a snow day, so people are at home.  Person A and B
> both decide to work on the same project, but thanks to our use of
> Mercurial, this doesn't mean that Person B's changes are lost when
> Person A pushes his work back to /var/www/html/lasersharks.  Instead,
> the changes of Person B and Person A get merged (presumably by "hg
> merge" on the dev server?) so that once again, the project there in
> /var/www/html/lasersharks has both sets of changes...and we can all
> view these from home just by setting up a ssh tunnel to the dev
> server's port 80.
>   

Actually, Person A's changes and Person B's changes could co-exist, but 
merging would be done by someone pulling those changes, performing the 
merge, then pushing the result. You could let A and B push their 
changes, and this might result in a warning about "multiple heads" 
(which just means that A and B changed the project in different ways), 
and you might then log into the server and merge those heads in order to 
see a sensible combination of their changes, but many people would argue 
that (as I wrote in the last sentence) you'd get someone to do the merge 
on their own machine and then push the result.

> I think what Mike suggested should work, so I just need to sleuth out
> the quirks and make sure I'm doing it all correctly.  But if those of
> you who know Mercurial, Subversion, and other ways to do this have a
> better solution, please feel free to LMK.  I've invested enough time
> in Mercurial thus far that I really HOPE it's the way to go, but if
> not, no better time to switch than the present.  We really do feel
> that having changes made on the dev server web root is the way to go,
> and we want to have a central location where changes are put so that
> everyone's on the same page each time a commit is made.
>   

Although some of what you're suggesting might not match other people's 
"best practices", I don't see anything inherently unreasonable about 
what you want to do. Although "CVS-like practice" is described on the 
Wiki's working practices page 
(http://mercurial.selenic.com/wiki/WorkingPractices) in a way that would 
persuade those wanting to "better themselves" to grasp one of the 
alternatives, I wouldn't be surprised if the majority of distributed 
version control usage actually stayed fairly close to such centralised 
practices.

> Again, I appreciate people's time.  Sorry if I sound down about this
> -- as someone (maybe Mike?) suggested, once I'm up and running it will
> all make more sense and be easier than I think.  But compared to so
> many open source projects I've used, boy, the learning curve here has
> been steeper than I expected.
>   

I know that you've since chosen Subversion to handle your choice of 
workflow, but any insights into improving the documentation are welcome.

Paul