Re: Doc build hanging (with memory leak?)

[Joseph Rushton Wakeling]

On 14/05/12 11:41, David Kastrup wrote:
>

Before saying anything more, I'm sorry if my earlier email was offensive or 
intemperate; it wasn't meant to be.  I was writing out of concern for the ease 
of contributing to LilyPond (more on that in a moment).

> Have you actually used Rietveld for reviewing code?  It does a job that
> the mentioned tools don't.

If I understand correctly, Rietveld is a server-side app.  My objection isn't to 
Rietveld per se, but to the requirement to use a custom app on my system to get 
my code _into_ Rietveld.  This seems to be Rietveld's fault, so I'm sorry if it 
seemed like I was apportioning blame to the LP team.

I _strongly_ dislike any requirement to install project-specific custom tools 
and system tweaks in order to contribute.  It's not just about the personal 
hassle, but about wanting to lower the barrier for all contributions and in 
particular for off-the-cuff contributions.

That's not saying that I don't understand you have very good reasons for wanting 
to use Rietveld, or that I have a better alternative up my sleeve.  I was just 
astonished to be asked to run a tiny doc patch through a code-testing service.

> You can use any branch name for "git cl upload".  Using stuff other than
> master has the disadvantage that the diff might not apply for the
> centralized regression tests.

To be sure that I've understood correctly, are the "master branch/separat 
branch" sections of
http://lilypond.org/doc/v2.15/Documentation/contributor/commits-and-patches#uploading-a-patch-for-review

... referring to the name of the local branch on my machine, or the LP repo 
branch that it's based on?  It just seems utterly weird that the name of the 
branch on my machine should matter at _all_.

If it's referring to the server-side branch, then to my eyes the docs aren't 
clear enough in meaning ... :-)

> I think you are not clear about the number of merge conflicts such a
> style would cause when using LilyPond.  It is bad enough as it is.

Isn't normal practice to expect the submitter of a patch to merge or rebase from 
master and resolve any conflicts before it gets merged in?

> > I'm not proposing "commit first, question later".  I'm saying that the
> > process of _submitting_ a patch or merge request should be trivial.
>
> It is.  Have you actually tried it?

It's not trivial if I have to install custom code in order to submit a tiny doc 
patch!

If I were hacking on LP itself then it would surely be a small issue by 
comparison, but I wasn't, and I don't think small tweak-y contributions should 
be treated this way.

> There are reasons the show is run in the manner it is, and the reasons
> are not just because everybody except yourself is an idiot and just
> waited for you to tell them how to make everything simple and smooth.

I certainly didn't intend to suggest that and I apologize unreservedly if it 
seemed that way.

> I could be malicious and offer you the responsibility to make everything
> better, but the fact is that I am not in the position to even make such
> an offer, and a lot of hard work and discussions have gone into working
> with the current system, and not all of the reasons are strictly
> technical but are also done in order to utilize the distribution of
> talent available for LilyPond best.

I think if anything is clear it's that LP is the result of an extremely large 
amount of work by a small and very dedicated group of people.  I _do_ appreciate 
that, very much indeed.

> There is no sensible way around learning the ropes before attempting to
> replace them.  Certainly people would welcome a transition to systems
> better suited to git.  But your hand-waving proposals not even include a
> substitute for the Rietveld vetting system (like, say, Gerrit) including
> organizing the hosting for it, let alone adapting the existing workflow
> and toolchains.

My remarks were made in haste as I was not expecting such an extensive response 
to my original, short remark on the complications of the process.

I'll add an extra story which may give some context to my reaction.  The last 
time I attempted to make a contribution to LP was probably about a year ago -- 
there was some documentation work I was interested in doing.  At this time there 
were some issues with the doc build system where make did not automatically pick 
up on changes to input files.

The workaround which several helpful list members suggested was to 'touch' one 
of the files for the manual concerned.  The problem with this workaround was 
that it meant that everything in the manual had to be rebuilt -- it was much 
less than a full doc build, but still a large build process.  I wanted to make 
sure I hadn't missed anything, so I asked if there was really no way to get the 
rebuild to just cover my changes and not all the extra untouched material.

... and at this point someone chipped in with a long and fairly unpleasant 
lecture along the lines of, "Sure, you can read all the make documentation and 
go through the build scripts and rewrite them all ...".  It was a big and nasty 
shock especially as I'd been perfectly polite and was eager to contribute.  It 
was extremely demotivating and I was quite angry about it, not only on my own 
behalf but because I thought it was an awful way to treat anyone who was 
actually wanting to make a contribution.

Now, there could be a plenty of reasons why that developer had that reaction -- 
just a bad day, feeling undervalued, too often getting complaints about the 
system without offers to help -- but it really made me wonder about the 
project's attitude to potential contributors.

That experience may have coloured my reaction when a small and easy-to-include 
patch, knocked off as a friendly gesture to try and make sure someone else 
didn't have the same scary experience I did with the new doc build system, got 
in response a terse instruction to submit it via a complicated and unfamiliar 
set of custom tools whose whole raison d'etre is to test code, not docs.

I'm not trying to suggest that anyone is evil, bad or stupid, but it really 
didn't seem to me to be the best way to handle things for a case like this.