Message-ID: <688816427.8819.1409437736992.JavaMail.email@example.com> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_8818_458235567.1409437736991" ------=_Part_8818_458235567.1409437736991 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
A "patch" is the set of differences between two versions of th=
e same file. Patches are used to send someone the exact changes that you ha=
ve made to your version of a program or a document. They can then apply tha=
t patch to their version to merge the changes and bring their version up-to=
-date with your version.
As our example we use the contribution of a = simple documentation patch for the Castor project. The principles apply to = any project and to any type of file, e.g. *.xml, *.java, *.xsd, etc.
Anyone who wants to contribute to a project. This document addresses the= basics, so as to get new people started.=20
Our example describes the use of command-line tools for a UNIX system. O= ther tools can be used, as long as they produce a "unified diff".==20
Contributers should have:=20
cvs diff -ucommand.
Here is how to proceed.=20
A "Patch" is the set of differences between two versions of th=
e same file. A patch comprises one or more "diff" files. These di=
ffs are produced by the program of the same name: diff.
Here is an ex= ample of a single diff for one of the Castor How-to pages, where we are sug= gesting a minor text change. Do not get frightened. These are just human-re= adable instructions to the "patch" program.
That is a "unified diff" ... there a some lines of context on = each side of the changes. This patch is basically saying "Change the t= ext on line 208".=20
Let us now go though the process of preparing that patch. Go ahead and e= dit your local copy of the document at $CASTOR_HOME/src/doc/jdo-howto.xml.<= /p>=20
Ensure that it is valid XML using your favourite XML editor or an extern= al validating parser. Please do not leave it up to the poor committer to fi= x broken XML.=20
Run the '
build doc' target to be sure that links are not br=
oken and that the new document is presented as you intend it to be.
If you are using the HEAD of CVS then ensure that your working copy is u= p-to-date. Of course, if you are using a previous public release version of= Cocoon, then it is already up-to-date.=20
Prepare the diff file. CVS will contact the remote repository, ensure th= at your working copy is up-to-date, then compare your local copy with the m= aster repository.=20 =20
Prepare a brief explanation of what your patch does. Get this ready in a= text file before you go to Jira. See further hints about this in the "= ;Description" section of the How-to Jira.=20
To contribute your patch to a specific project, use Jira - The Codehaus = Issue Database. The procedure is explained in How to Contribute a Patch via= Jira.=20
A patchfile can contain the differences to various individual documents.= For example, the following command does that ...=20 =20
However, be careful not to go overboard with this technique. When produc= ing multiple diffs in one patchfile, try to limit it to one particular topi= c, i.e when fixing the same broken external link in various pages, then it = would be fine to produce a single diff. Consider the committer - they will = find it hard to apply your patch if it also attempts to fix other things.= p>=20
Ideally you will prepare your patches against a CVS repository. There ar= e other ways to do this. They do create more work for the committers, howev= er it may be the only way that you can do it. We would certainly rather rec= eive your patch however it comes. As a matter of fact, we would politely as= k you first to send us a unified patch.=20
You could get the source document via the web interface to CVS. Here are= the steps ...=20
diff -u jdo-howto.xml.orig jdo-howto.xml > $WORK/castor/patch/= jdo-howto.xml.diff