[documentation] [Documentation task] Reorganizing the Patch docs
dww
drupal-docs at drupal.org
Mon Jan 15 20:38:48 UTC 2007
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: dww
Status: active
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
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.
------------------------------------------------------------------------
Mon, 15 Jan 2007 13:12:53 +0000 : add1sun
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.
More information about the documentation
mailing list