how to structure some disruptive patches

Hi Rob,

I've been working on cleaning up the docbook function documentation
in the device tree files.  The resulting patches could interfere with
code patches, so I want to figure out how to structure the documentation
patches to avoid that.  I would like your opinion and suggestions on
the subject.

First premise: this set of documentation changes is a second class
citizen compared to code changes.  Any patch from this set can be
dropped any time it interferes with a code patch.

I started the project with the simple intent of fixing what was
clearly broken.
  - fix syntax errors
  - fix mismatches between actual function arguments vs docbook
    list of function arguments
  - fix mismatches between function return type (void vs anything) and
    values vs docbook return types and values
  - fix factually incorrect descriptions of what the function does

When I was making those changes, I found also found documentation
that was somewhat cryptic or otherwise hard to understand.  I also
found that the description of the same item was described in a
wide variety of ways in different docbook headers.  I made an
effort to also clean that up.

The result was a large patch series (that was not totally complete):

   15 files changed, 1414 insertions(+), 730 deletions(-)

plus around 150 lines of change to docbook files so that
the device tree man pages would be created.  I did not
add any other significant docbook documentation of device tree.

There are at least a couple of approaches I could take for
submitting patches (and would be glad to hear of any other
approach that I did not think of):

1) The big ugly patchset referenced above, one patch per
   file.
     pro: exposes what changes were made to each function
          documentation header
     con: very dense and not very readable
     con: the mechanical corrections create a lot of noise if
          the reviewer wants to view actual content changes
     con: probably more likely to conflict with code patches
          in a way that is not easily fixed

2) Split method 1 into stages (one patch per file for each stage).
   Examples of some possible stages are:
   - white space fixes
   - syntax fixes
   - incorrect argument list fixes
   - incorrect return type fixes
   - incorrect return value fixes
   - incorrect behavior description fixes
   - confusing behavior description fixes
     pro: it would be easier to review patches for many of the stages
     con: a lot more patches
     con: maybe difficult to handle conflicts with code patches
     con: maybe difficult to rework patches for review comments (changes
          for an earlier stage are likely to impact a patch for a later
          stage)

3) Do one patch series to remove all docbook function header documentation.
   Do a second patch series to add the updated docbook function header
   documentation.  For each of the two series, one patch per file.
     pro: the patches are much easier to read
     pro: it might be easier to resolve conflicts with source patches
          (either you dropping a few hunks or me redoing the docbook patch
          to remove the conflict)
     con: the actual changes to what the documentation says are not visible

My current version of the patches is against 4.7-rc2.  I will have to update
this to 4.7 or 4.8-rc1 (I would assume that 4.8-rc1 would make more sense).

One comment that applies to all of the above approaches is that I could
attack subsets of the device tree files instead of trying to do all of
them at the same time.

What do you think of all of this?

-Frank
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html