Re: hurd-web/hurd/translator/unionmount.mdwn (was: News 2009-08-31)

[Arne Babenhauserheide]

Hi, 

Am Dienstag, 8. September 2009 09:08:23 schrieb Sergiu Ivanov:
> I can see your point, but please note that if I were to think of the
> Hurd wiki in terms of a version controlled entity, I would create a
> personal branch and wait for approval from the authorized person to
> move the corresponding modification in the master branch.  

I think there are several different ways of seeing history, all depending on 
how people interact (and how many people read the history). 

One is to see history as a decision record.  You create clean patches and show 
them to people to propose a change.  In that case you need a clean history, or 
you need to flatten your local history into distinct patches before publishing 
it.  When people read your history, they see the effects of your groups 
decision process, but not the process itself.  When you have very complex 
systems or very many people interacting, this looks to me like the only way to 
avoid running into problems.  The same might be true for companies who need to 
be able to clearly blame people for errors.    

Another way is to see the history as a means to synchronize the work and as a 
simple track record.  It makes it easier to work distributed, because work can 
more easily be merged, but it isn't necessary for the history to look pretty 
to someone outside.  You don't need to turn everything into a final patch, 
because people can simply skit over change descriptions like "typo" and such, 
and more importantly, the final look of the history isn't important.  If you 
work in a small project which regularly synchronizes or in a project where the 
parts aren't too tightly interwoven, this can increase the development speed.  
Getting something perfect before publishing means that others have to wait 
longer before they can include and test it.  And if everyone polishes very 
much, it means that everyone has to wait until everything is polished (and 
many things might become stale and disappear before even going public).  

I use the second approach most of the time, since I don't currently work in 
big groups and the projects I do aren't so complex that small changes can 
throw off everything (I hope Thomas doesn't hate me for the many "typo" 
commits...). 

If I were in a big group where people don't really know each other, or in a 
project where maintenance is harder than creating the data, I'd switch to the 
first way, though.  

> However,
> it's obvious that creating a personal (private) branch in the hurd-web
> repository is rather meaningless since nobody can see it anyway.
> 
> OTOH, if I do just commit a change to the master branch right now and
> should it be decided that this change was inappropriate later, there
> would be two ways out: either remove the commit from the middle of the
> history or do clean-up commits, both of which are rather ugly.

Do you mean, they either are ugly for people who want to synchronize their own 
repository, or they are ugly to those who want to read the history later on? 

For me the first is a concern, but the latter doesn't matter that much for a 
wiki.  A wiki is meant to be quickly edited by many people.  A VCS doesn't 
change the kind of project it's supporting (for example I version control a 
roleplaying rulebook I work on).  It does give us additional options, though.  

More exactly: Thinking a lot about the latter can eat far more time than 
cleaning up afterwards.  And a quick clean up commit like 
"moved the union mount description to foo because bar and baz" 
doesn't look ugly to me.  It's clear what it does, so I don't even have to 
look at the patch, and its effect is clearly contained.  

And our wiki tends to get out of date, so updating status or providing current 
information is our bottleneck.  

On the other hand, the Linux kernel has so many contributors, that 
coordination and maintenance is a main bottleneck, so it's clear why they 
require polished patches.  


## Rule of thumb for committing

As a rule of thumb for the wiki I'd propose[*] to simply add anything which 
either needs almost no maintenance or which you are willing  to maintain 
yourself (and for which have the time for maintaining).  All naturally under 
the pretext that you think it's useful and it doesn't make the page harder to 
navigate for visitors.  

[*]this means: Olaf, Thomas, does that sound OK for you?


For example a blog post is a point in time.  It doesn't need maintenance, 
since it carries a date and it is clear to the reader, when it is out of date. 

On the other hand the News on the main site are a feature I saw as necessary 
but which needs maintenance, because else it does more harm than good.  That's 
one reason why I decided to do the months of the Hurd.  That way the news will 
always include new items and people can see that the Hurd is moving forward 
(few things are worse for an active projects external appearance than a stale 
news list where the latest news are three years old).  

The same way any "status" site needs to be maintained, but a track record "I 
worked on the Hurd during the GSoC 2009" only needs maintenance until the 
activity is finished.  

And when you add a page and don't know where it belongs, that's an indication 
that visitors would also not know where to search for it, so our structure 
needs to improve some more :) 

> However, while writing this, it occurred to me that I could as well
> put the short description into hurd-web/user/scolobb .  After all,
> since the GSoC is officially past its end, I can mention the fact and
> provide a short description of the result of the program.

The update would definitely be good.  That page is what people will be looking 
at to see how your GSoC did go.  

> > We don't lose anything when those who have most knowledge about the
> > special area just act, but we lose a lot of time by waiting too much.
> 
> That's a philosophical point :-) Just acting is not always the best
> way to do things.  This may lead to race condition :-) 

:) 

That's true, but in a VCS it only means duplicated work and not lost work.  

Also I assume that in the time we already spent on discussing *where* to put 
the information, we could already have written and then reworked a good part 
it - and moved it later in less than a minute after getting feedback.  

> Anyway, I hope
> the solution I suggested above (adding the documentation to my
> hurd-web page) should be good.

I think you should also add a link from the translator proposal to your status 
page, then it will work out very well. 
 
> I'm afraid this could introduce ugliness in the history.
> 
> It has just occurred to me that a fair part of my thinking about this
> problem is occupied by taking care of the history being nice.  I
> wonder whether it's normal :-(

I think it is.  

I also fall into the trap at times (it's like reputation: "Look, I did good 
work, see how nicely it shines" "but does it do anything useful?" "no, but 
look how it shines" :) ), and there are times when a clean history is 
important (and cluttering too much can make it harder to search for bugs later 
on).  

But overally what most other people see and care about (especially in the 
wiki) is not the history but the final text.  
 
> > PS: I now use the wiki via Mercurial and the hg-git extension.  That way
> > I avoid getting bitten by git again ;)
> > I only need got for *creating* short-lived branches (sicne I can already
> > do the merging from mercurial).
> 
> That's great :-)
> 
> Seeing how advertently you propagate Mercurial in every applicable
> task, I think I'll have to have a look at it :-) It should be worth
> the time ;-)

Maybe I should write a disclaimer into my signature : "I really like 
Mercurial, but please also ask Olaf why git is great, so you see both sides" 
:) 

I assume it's mostly personal preference.  I like the feel of Mercurial far 
more than that of git, but technically they are about equal.  Philosophically 
they are quite different, though.  Git advocates mutable history and private 
branches which you rebase before you publish, while Mercurial advocates 
immutable history (what's done is done) and early publishing of private 
branches to be merged later on (you need to use command line options to 
*avoid* publishing all branches when you push). 

Naturally git can be used with immutable history (only allow fast forward 
pushes, iirc) and Mercurial can rebase (activate the rebase extension) and 
keep private branches (hg push -r REV only pushes the branch with that 
revision, up to the revision), but these aren't the default ways of operation.  

What I also prefer about Mercurial is that it's very hard to shoot yourself in 
the foot with the commands you get when you don't activate any extensions 
(even though the extensions are shipped with Mercurial and thus part of the 
program, they aren't active by default).  That makes it hard to break and 
quite useful for less technical minded people, too.  

Also another disclaimer is needed: I actively contributed to Mercurial up to a 
month ago (for example I wrote most of the content on http://hg-scm.org )and 
only stopped because I have to concentrate on learning for my diploma exam, 
now.  So I decided to stick to the Hurd, because I though that I can make more 
of a difference here while needing to invest far less time (writing the news 
should only take about half an hour to an hour per week). 

So my view is clearly *not* unbiased :) 

Best wishes, 
Arne

--- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- 
   - singing a part of the history of free software -
              http://infinite-hands.draketo.de

signature.asc
Description: This is a digitally signed message part.