[documentation] [Documentation task] Reorganizing the Patch docs

[add1sun]

Issue status update for 
http://drupal.org/node/109114
Post a follow up: 
http://drupal.org/project/comments/add/109114

 Project:      Documentation
 Version:      <none>
 Component:    Developer Guide
 Category:     tasks
 Priority:     normal
 Assigned to:  Anonymous
 Reported by:  add1sun
 Updated by:   add1sun
-Status:       duplicate
+Status:       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.




add1sun



Previous comments:
------------------------------------------------------------------------

Sat, 13 Jan 2007 19:20:58 +0000 : add1sun

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?




------------------------------------------------------------------------

Sat, 13 Jan 2007 19:29:49 +0000 : add1sun

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





------------------------------------------------------------------------

Sat, 13 Jan 2007 20:49:04 +0000 : karldied

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."




------------------------------------------------------------------------

Sat, 13 Jan 2007 22:04:34 +0000 : sepeck

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




------------------------------------------------------------------------

Sat, 13 Jan 2007 22:04:54 +0000 : add1sun

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.




------------------------------------------------------------------------

Mon, 15 Jan 2007 08:50:41 +0000 : sepeck

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


Please follow up with dww on that issue.