db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Daniel John Debrunner <...@apache.org>
Subject Re: How to commit documentation patches?
Date Mon, 14 Aug 2006 21:16:55 GMT
Jean T. Anderson wrote:

> So far the process has been pretty ad hoc. Last week I offered to do
> 10.2 doc commits [1]:
>>I'll volunteer to keep these on my radar. If reviewers will please add a
>>comment to the Jira issue that the patch is good to go (or not), I'll
>>then commit the ones that are ready.

> Of course, any other committer is also welcome to jump in, but it looks
> to me like everyone is massively busy.

This is a problem for the community, we need more than just Jean to
commit documentation patches. That's why I started looking at getting
setup, I hope other committers do the same.

> The main thing I'm looking for is a clear comment in Jira that indicates
> a patch is ready to commit.  There are *lots* of doc patches and I don't
> have time to review them; I'm relying on technically knowledgeable
> reviewers to indicate a patch is ready.

Seems a reasonable approach given "with a commit-then-review process,
the Committer is trusted to have a high degree of confidence in the change".

I wonder though how a committer should handle a typical exchange like
this for a doc change:

  - patch submitted
  - reviewer makes comments
  - revised patch

Now it seems there are three possible choices for a committer:

  A) commit the patch without any further review
      + gets the patch submitted the quickest
      + allows more eyes on the change early
      - chance for wrong information applied to docs

  B) reviewer the patch themselves and then commit
      + almost as good as 1) on the time frame
      - extra time committment by a committer
      +/- less chance for wrong information (depends on if committer
knows the area)

  C) wait for an additional review (by anyone) [Jean's approach]
      + least chance for wrong information (but still a chance)
      - longer timeframe before committing
          * initial reviewer may not have time to review the revised patch
          * other reviewers may not appear

I think the choice can depend on the changes in the last patch. With a
revised patch that just fixes a spelling mistake noticed by a reviewer,
it seems A) is better. With a revised patch that re-works a whole
concept, e.g. "authorization" to "connection access", another review is
probably justified.

I believe though the two advantages for A) outweigh the chance of wrong
information being committed due to lack of that final review, the
problems will get picked up at one point. Of course this is good for the
trunk, maybe not a release branch.

Of course C) could be speeded up if we had more reviewers, maybe
contributors interested in documentation who want to gain merit could
help out by reviewing doc patches. Especially while they are in this
final phase (all review comments addressed), Jean (or other committers)
waiting for the final stamp of approval.

Believe it or not, I've tried to work more towards A) in committing code
changes, if the code works, passes the test then commit it even if it
isn't perfect. The imperfections can be logged and worked on later, e.g.
better factoring, more comments etc. Get more eyes & testers on the code
earlier. I do have a threshold though, if all the tests pass but the
code approach seems to take Derby internally in the wrong direction then
I like to see the changes up front.


View raw message