28487 - Add information on how to prepare/submit patch files

Status: VERIFIED FIXED

(www.mozilla.org :: General, enhancement, P3)

Description

[Frank Hecker]

The "Getting Involved" page briefly mentions using "cvs diff -u" to prepare
patches for submission, but I think many users will need more explanation than
that. I suggest modifying the "Getting Involved" page to add more info, or
(preferably) creating an entire new page "How to Submit Patches".

The page would describe two overall ways of preparing and submitting patches:

1. Developers with their own Mozilla CVS repository should use "cvs diff -u" and
redirect output to a file:

  $ cvs diff -u >patchfile.txt

Does the developer need to be at a certain level in the Mozilla CVS tree? If so,
this should be added to the example. What about Windows developers; would they
use this same command? If not, what? What about Mac developers?

2. Users who do not have their own CVS tree should use the diff tool or
equivalent. The easiest case is for single files:

  $ diff -u oldfile newfile >patchfile

Should they follow a particular convention for naming the files, for example,
name the new file as the old filename appended with "-new"?

  $ diff -u foo.xul foo.xul-new

Or should they rename the old file with a "-old" suffix and have the changed
file have the original name?

  $ diff -u foo.xul-old foo.xul

Which way works better for people applying the patch?

How about Windows users?  Where can they get a copy of diff if they don't
already have it?  From the relevant page of the Open Directory:

http://dmoz.org/Computers/Software/File_Management/File_Comparison/Windows/

there appear to be several diff utilities for Windows that might work. Are there
any particular ones we recommend to produce the correct patch file format?

What about diff utilities for Mac users? For that matter, do all current Unix
systems have a diff with the "-u" option?

What if the user has several files with fixes?  Should we recommend use of "diff
-r"? Is this functionality present in the Windows or Mac diff utilities? Or
should we just recommend that users send several patch files, one for each
changed file?

Finally, are there any special considerations when attaching patch files for
submittal? Should users always send them as email attachments? Any special
considerations in terms of DOS vs. Unix vs. Mac line formatting? What about
files containing more than just 7-bit ASCII data?

Comment 1

[Daniel Wang]

-> gerv

Comment 2

[Daniel Wang]

Attachment: patch

add link to http://www.mozilla.org/cvs.html and http://www.mozilla.org/hacking/

Comment 3

[Gervase Markham [:gerv]]

r=gerv. Do you have the ability to check this in, Daniel?

Gerv

Comment 4

[Daniel Wang]

no

Comment 5

[Gervase Markham [:gerv]]

Please apply for website CVS access, then. :-)

Fixed.

Checking in get-involved.html;
/cvsroot/mozilla-org/html/get-involved.html,v  <--  get-involved.html
new revision: 1.37; previous revision: 1.36
done

Gerv

Comment 6

[Daniel Wang]

v