Re: Updates to ch02.xml

Matt Blais wrote:
> Actually I was expecting someone to proof my changes, since it's

Absolutely. Review of changes is an important part of this project. At least two of us did start to proof-read your changes, and provided feedback. We stopped after hitting many trivial items, and will continue when you have fixed those; or, if you disagree with our feedback, when you convince us that you were right. So you mean that you would rather I had struggled through to the end of your patches and provided all of the feedback in one go? That would have been more difficult for me because I can't use a visual diff program or compile to HTML until I get at least a well-formed patch (without wrapped lines).

> generally accepted where I come from that it's not a reasonable
> expectation for a person to be able to proof their own writing.

Indeed. Of course you cannot judge subjective matters of style or conventions that you have not yet heard of. But I expect you to review your own patch before posting it, to catch as many simple mistakes as you can. It doesn't matter if you miss some things, as a reviewer will point them out and then you can post an updated version until a reviewer is happy with it and commits it to the project. The more carefully you review your own changes, the quicker this process is, and the more friendly and willing the reviewers will be.

When you do this sort of review of your own work, each time you find a particular kind of mistake, such as a mis-used apostrophe or a bad indentation, search through for other instances of the same thing and correct them all before continuing the review.

> I'm a bit confused as to how things work around here. What are the
> standards for accepting patches (and docs, specifically), and who
> decides?

I only joined the project this year, and cannot give a definitive answer. In my opinion, a change will only be accepted if it:
- corrects an error (even a trivial error); or
- makes a definite improvement.

And such a change will usually not be accepted if it:
- introduces a new error; or
- breaks a project style convention (e.g. line length should be less than 80 characters); or

C-Mike Pilato gave an answer to "Who decides?".

> I'm feel like I'm getting different opinions about what sort
> of changes are welcome. I thought I read the docs regarding "How to
> help out" with Subversion, but now I'm feeling like I must have missed
> something.

OK. I'm guessing that you are talking mainly about your changes of wording, where you have re-written a sentence so that its meaning is the same as before but its style is more pleasing to you. And I do remember that you specifically offered "to proofread it for grammar and clarity", and were encouraged to do so.

In this case, if I think most reviewers would judge the proposed new version to be definitely better than the old version, then I will accept the change. If the new version looks OK but the old version was also OK, then I would prefer not to make the change, because it is extra work for me and is just as likely to be changed again by someone else.

If a change is rejected as "no better than the original", but actually you had a tangible reason for the change (such as making the sentence style consistent with the rest of the book), then please object and say why.

> I don't want to waste your time OR mine, so I'm not going to do any more
> with this until I'm a little more clear about what's expected and
> accepted. I gather this must be a common situation in the open-source
> world (to which I am NEW).
>
> I'm happy to help out and contribute, but I need just a LITTLE more
> structure to work within. If y'all are too busy to provide that, I'll
> understand - no problem.

I'm not sure if this is what you mean by "structure" - but ... Personally I will review your changes further when I receive a well-formed version - without indentation changes, obvious errors, etc. And if most of the patch represents one kind of change (such as the change in style from "his or her" to "their") then I would want that issue resolved before continuing.

I hope this helps you to understand why you got the rather negative response that you did get. If you still have the will to contribute to Subversion, I am happy to try to answer further questions and help you to provide the most useful sort of patches.

- Julian

>
> --Matt
>
>
>>-----Original Message-----
>>From: Julian Foad [mailto:julianfoad@btopenworld.com]
>>
>>cmpilato@collab.net wrote:
>>
...
>>>Alright, that's it. I'm bailing on this review, and -1 on the patch
>>>until it comes back with all this singular/plural business cleaned up.
>>
>>I agree. (As a specific point, the use of "their" to mean
>>"his/her/its" is common in conversation but not very good
>>written style. So the benefit of it sounding more like
>>natural language is countered by the drawback of it sounding
>>less professional.)
>>
>>The thing is, Matt, that for each change you make, often more
>>than one person will review it, and they have limited time to
>>spend on it. Therefore it is worth concentrating only on
>>things that are definitely wrong or can be substantially
>>improved. For what it's worth, I agree with the spirit of
>>most of your changes - including "stepping on someone's toes"
>>being the natural idom rather than "feet" - but there are a
>>very great number of changes here (especially in ch03.xml),
>>and several of them are ones that a different proof reader
>>would change back to the other way. In those marginal cases,
>>prefer making no change.
>>
>>Thanks for your patience and I hope this doesn't put you off.
>> I (and we) are grateful for many of the corrections and
>>improvements that you are offering.

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Wed Aug 27 13:15:39 2003