This is my first real foray into docs work so let me know if I'm going about this incorrectly.

I am learning how to do patches and patch review and I find the Handbook's current docs a bit confusing. While pages do refer to other pages, the order in the menu and the way everything is broken out made it confusing. I want to propose a little reorg of the existing docs and then I will also be working on improving some of the pages themselves (notably Create patches and Submit patches sections) so it is a smoother ride for newbies like me. Here is my proposed new ordering, this all goes under Contributing to Development > Patches:

Background: the basic concept of Diff and Patch
Applying and Reviewing Patches
HOWTO: Apply patches
Common problems
Apply Patches on MacOS X
FileMerge
Apply patches in Windows
Cygwin
Patch
UnxUtils
HOWTO: Set up a test environment to review patches
Tips for reviewing patches
HOWTO: Submit patches for Drupal
HOWTO: Create Patches
Create patches in MacOS X
Create patches on Windows
CVS
Several win diff programs
Subversion
TortoiseSVN
UnxUtils
WinCVS
WinMerge

I have grouped Applying and Reviewing since you need to know how to apply them in order to review them but if folks think it makes more sense to separate them, that would still flow I think (that is have as majors: Background, Applying patches, Reviewing patches, Submitting patches).

Thoughts, comments, rotten tomatoes?

Comments

add1sun’s picture

add1sun commented

Ack, sorry, I really should have a habit of hitting preview first.

let's try that structure one more time:

  • Background: basic concept Diff & Patch
  • Applying and Reviewing Patches
    • HOWTO: Apply patches
      • Common problems
      • Apply Patches on MacOS X
      • Apply patches in Windows
    • HOWTO: Set up test env to review
    • Tips for reviewing patches
  • HOWTO: Submit patches
    • HOWTO: Create Patches
      • Create patches in MacOS X
      • Create patches on Windows
karldied’s picture

karldied commented

I expect the Background page would be a welcome addition. To me, the doc often uses more levels than it needs. Why not "Applying patches" and "Reviewing patches" be separate and at the same level? Same for "HOWTO: Submit patches" and "HOWTO: Create patches"? Though it is easy to think of creating a patch as the necessary step of submitting one, it really is its own operation. Submit should perhaps say, "Create patch that meets Drupal standards, then submit an issue this way."

sepeck’s picture

sepeck commented

We need dww and heine to review changes to these sections.

add1sun’s picture

add1sun commented

Yeah, like I said, I'm not opposed to splitting applying and reviewing out. The main reason for combining submitting and creating patches is due to the content of those two sections now. If they are split, then they need to be rewritten a bit because Submitting has all the steps, including creation using the "cvs diff" command, while creating only talks about regular diff (and not very thoroughly - this is why I want to edit it a bit). When I was looking at the docs I immediately went to Create patch and was basically misled because it is not as thorough as the instructions in Submit. But the Submit instructions use cvs diff command which I couldn't use.

Generally, I can't see why I'd make a patch without it being part of the process of submitting it and that is how the current Submit Patch page is written so I still think it makes sense to combine them.

sepeck’s picture

sepeck commented
Status: Active » Closed (duplicate)

actually, this appears to duplicate the issue open here.
http://drupal.org/node/93946

Please follow up with dww on that issue.

add1sun’s picture

add1sun commented
Status: Closed (duplicate) » Active

It is perhaps related to that issue but it is actually a different section of the handbook and while Patches are often associated with using CVS, it is not a required part and really is a bit different (which is why Patches is not under the CVS section of the handbook). I will follow up in that thread to point folks here to look as well but this is not actually a duplicate as far as I can see.

dww’s picture

dww
we/he/they
commented

i agree, this is its own issue, not duplicate of the CVS handbook stuff in http://drupal.org/node/93946.
i'll try to review the proposed changes above in the near future, but it might be a little while.

thanks,
-derek

dww’s picture

dww
we/he/they
commented

please see my extended proposal for this, building on top of what add1sun started:
http://groups.drupal.org/node/3455

dww’s picture

dww
we/he/they
commented
Assigned: Unassigned » dww
Status: Active » Fixed

after getting add1sun and webchick's approval, i just implemented the full proposal in the d.o handbooks. now it's just a question of editing some of the pages, but that's a topic for other issues. the actual reorganizing is now done, so i'm marking this fixed.

Anonymous’s picture

(not verified) commented
Status: Fixed » Closed (fixed)