Software (and text) management

[Thomas Schwinge]

Hello!

Instead of following up to each email individually, I'll combine some
answers in here.


On Tue, Sep 08, 2009 at 12:28:09PM +0200, Arne Babenhauserheide wrote:
> 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).  

Nice descriptions!

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

I don't care -- though I think that you could probably mostly reduce them
by simply re-reading what you're going to commit...  :-)

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

Or put it this way: the first way is absolutely necessary if your
software is being used out in the wild, and any new bugs you introduce
(while trying to fix others) would be directly visible by others and
(potentially) cause harm to them.  That is, released software, considered
stable.

Now, for the whole set of Hurd software, I think that we can consider all
of it experimental, in development, not stable and released.  Thus, we're
rather entitled to do it the second way, for easier procedures.

And of course, even when going the second way, it doesn't hurt to apply
as many principles from the first as possible -- as long as they don't
interfere with what you're trying to do in the first place.


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

Agreed.


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

I concur.  And I even propose to simply add anything that conveys a bit
of information you discovered and that is not yet present.  Of course,
all this doesn't relieve you from thinking about where to store your
information bits, but if you can't come up with the correct page, then
I'm even fine with you adding it to a page like TODO_unionmount, and then
we can later see about where to integrate it.  But then, the information
is there already, ready for the integrator to be used.

> 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 :) 

There definitely is work needed in this area, I agree.

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

Yes, but this page should only reflect his personal / the project's
status, and not the main documentation of the software he created.

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

Thank you, exactly my thoughts and words.


On Tue, Sep 22, 2009 at 12:10:43AM +0200, olafBuddenhagen@gmx.net wrote:
> On Wed, Sep 09, 2009 at 09:49:11AM +0200, Arne Babenhauserheide wrote:
> > It's a trap into which groups often seem to fall (in my experience).
> > I often discussed with a former roommate for hours how we could
> > perfectly do something and in the end we didn't have any more time so
> > we couldn't follow up on the "perfect" solution or had discussed our
> > motivation away.  
> 
> That's also a kind of over-engineering -- the dangers of which I have
> pointed out in other contexts :-)
> 
> (My problem is that while I learned not to *implement* unnecessarily
> complicated solutions, I haven't learned not to *think* too much in
> advance :-( )

Yes, clearly working this way needs training.  But there is absolutely no
problem with saying: ``look here, I created this, which can do A and B,
but not yet C -- for C I think we might do it like this, but that's for
later, *and is documented here*''.


On Tue, Sep 22, 2009 at 12:04:09AM +0200, olafBuddenhagen@gmx.net wrote:
> On Tue, Sep 08, 2009 at 12:28:09PM +0200, Arne Babenhauserheide wrote:
> > 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.
> 
> I agree: while I would advocate clean history for almost every coding
> project, a wiki is really a very different beast. The whole *point* of a
> wiki is keeping the barriers to contribution as low as possible. And
> there is no need to track regressions in a wiki, so a clean history is
> not really important.

Also, that's part of the reasons *why* we switched to this system in the
first place.

> Note though that in spite of the low barriers, even a wiki has
> considerable inertia: once something is done in a certain way, people
> are generally reluctant to change it, unless very are very sure that a
> change will be a substantial improvement. Thus I think that if you are
> very unsure about something, it still might be better to ask in advance
> in some cases...

This is true, but it only really applies to structural changes.  But in
the 94 % of cases of wiki edits (or here: discussed wiki edits) it's
simply about either adding information or fixing existing information.
Here we agree that it should just be done.


Regards,
 Thomas

signature.asc
Description: Digital signature