Revision of HOWTO Submit Patches to Correct MinGW Bugs or to Add MinGW Features from 2008, September 10 - 22:08

Printer-friendly version

You've identified a bug in a MinGW package, and you've developed a solution to correct the defect. So, how do you submit that solution, for inclusion in MinGW?

All user proposed modifications or enhancements to MinGW are subject to review and approval by the project administrators, and the project development team. By following the guidelines set out below, you will give your solution its best chance of being adopted, in a timely fashion.

  1. 'Base your Solution on Current Source Code, from the Official CVS Repository
    First you must determine where the Official CVS Repository for the package you want to submit patches for resides. Each package has its own Official CVS Repository and submitting patches based on up to date source code, from the appropriate CVS Repository, via the appropriate PatchTracker, will get your patch adopted into the source package faster.

    Once you've identified the correct CVS Repository, and located the files within it, which you need to modify, you should download clean working copies of each, in preparation for making your changes.

  2. Keep an Unmodified Reference Copy of Every File you Intend to Modify
    If you are working with CVS directly, the CVS Repository serves as your reference copy. Otherwise, you
    must keep a reference copy of every file you intend to work on; this will be required later, when you create your PatchSet.

    How you preserve your reference copy of the downloaded files is a matter of personal preference. A technique, which may be used successfully, employs a pair of distinct but related directories, thus:--

    • assuming that you have set up a top level directory called `sandbox, in which you will keep your working files, create the two subdirectories, `sandbox/current and `sandbox/working.
    • download the original copies of the CVS sources into `sandbox/current; (if you are working with a number of files, spread across a number of subdirectories, it may be convenient to replicate the structure of the CVS directory tree under `sandbox/current, and download the source files into their appropriate relative subdirectories, within the `sandbox/current directory tree).
    • never modify any of the files you have placed in `sandbox/current, throughout the life time of your work cycle, until you have completed and submitted your patch, and it has passed through the approval process.
  3. Make a Working Copy of the Files you Intend to Modify
    Having established the reference copy of each file you intend to modify, you should then make a second copy, in which you will make your changes. If you have adopted the paired directory technique, described above, and you are using MSYS, then this WorkingCopy can be readily initialised by making `sandbox your current directory, then executing the command:--

    ( cd current && tar cf - ) | ( cd working && tar xf - )
  4. Prepare a TestCase
    If possible, you should provide a small TestCase program, to demonstrate the validity of your patch. It is typical to use this to illustrate the effect of the defect you have identified, and also to demonstrate how your patch corrects this defect.

    You should develop your TestCase before you begin work on developing your patch; this way you can develop the TestCase code to properly demonstrate the correct vs. incorrect functionality you are attempting to rectify, and you may avoid falling into the trap of developing a TestCase which serves to better illustrate idiosyncracies of your patch, rather than its correctness.

  5. Modify and Test your Working Copy of the Affected Source Files
    You may use any development tools with which you are comfortable, (provided of course, that MinGW is used as the compiler), to prepare and test the modified code from which your patch will be derived.

    Always preserve the coding style of the original files; even if you prefer an alternative style, trying to impose that is a good way to ensure that your patch will be rejected!

    Do use the TestCase, which you have already developed -- you have, haven't you? -- to verify correct operation of your modified code, before you proceed to the stage of creating your PatchSet.

  6. Prepare the PatchSet
    A PatchSet should
    always be created in `diff -u format, with a minimum of three lines of context. Again, if you have adopted the paired directory layout for your workspace, and you are using MSYS, and again assuming that your top level working directory is called `sandbox, (and it is an immediate subdirectory of your $HOME directory), then a very convenient PatchSet may be created by issuing the commands:--

    cd ~/sandbox
    diff -Naur current working > patchfile.diff

    (This is convenient for you, because it captures all of your modifications into a single integrated PatchSet, comprising only one file; it is also convenient for the developer evaluating your patch, because he can apply your changes to his own set of working files, in his `working directory, by issuing the single command:--

    patch -p1 < patchfile.diff

    ).

  7. Write a ChangeLog Entry
    Providing an appropriate ChangeLog entry will increase the probability that your patch will be accepted. It must be formatted as specified in the GNU Coding Standards; further guidance on writing an acceptable ChangeLog entry may be found here.
  8. Document your Work
    Before submitting your patch, you should prepare documentation on what you have done, describing the defect you have corrected, or the new feature you have implemented; this should be formatted as plain ASCII text.

    For missing declarations or import functions in the mingw runtime or w32api it is essential to specify the source of the documentation on which you based your patch, or to otherwise provide proof that you have developed your solution through your own experimental effort. Never resolve an issue by looking at someone else's work (unless it is public domain). We only accept patches based on publicly available documentation, (MSDN is an acceptable source, as is any BSD or similarly licensed source; no GPL or LPGL licensed source is acceptable, unless your patch relates to a MinGW package which is already distributed under one of these licences), or on individual experimental effort, and never based on others' work, (particularly where that work may be proprietary). Note, in particular, that we adopt a much stricter standpoint on extracting information from Microsoft's SDK headers, than that taken by some other projects, such as Wine or ReactOS; consequently we will always reject, unconditionally, patches based on information extracted from files published by such projects.

    N.B. -- Failure to honour this requirement will disqualify your patch now, and may limit the usability of patches you submit in the future.

    When you implement a new feature, (for example, an implementation of a POSIX function which is not currently supported), you should also provide end user documentation, to explain how it is used in the Win32 environment. This should preferably be in the form of a man page, or a `texinfo' source file. Do not simply copy documentation from a GNU/Linux distribution; while that may be an acceptable source of inspiration, you should adapt it to suit the specifics of your MinGW implementation. `man pages should be provided in original `troff source format, rather than as preformatted ASCII text. Similarly, `texinfo documentation should be provided in `texinfo source format, rather than as preformatted `info files.

  9. Prepare a PatchSet Package for Submission
    While the PatchTracker will allow you to submit any number of separate files, as components of a single patch, you may find it more convenient to prepackage them into a single tarball, for one shot upload. The minimum content you should prepare for upload is:--
    • your `patchset.diff file, containing the meat of your patch.
    • your `ChangeLog.txt file, (assuming you used this name), containing your prepared ChangeLog entry.
    • any ASCII text documentation file you have prepared, describing your patch in detail.
    • any end user documentation you are providing, in `man page or `texinfo' source format.
  10. Submitting your Patch
    At last, you are ready to submit your patch!

    You should now proceed to the PatchTracker and select the Submit New, Add New Artifact, (or whatever new name SourceForge have adopted today) link, at the top left of the main window. Complete the displayed form, providing the following information:--

    • the PatchTracker category to which your patch belongs; (select this from the drop down menu).
    • an appropriate title for your patch; (type this in the `Summary' field).
    • a detailed description of your patch, in the appropriate field; (copy and paste this from the content of the ASCII documentation file you prepared earlier).
    • check the box to `Attach and Upload a File', then click the `Browse...' button to locate the tarball you prepared, containing all the files pertaining to your patch.
That's it. Do not set a group or a priority for your patch, or assign it to any individual; these are the project administrator's responsibility. Simply click the `SUBMIT' button, to complete your submission.

Site Status

Site maintenance completed May 25th, 2012 at 12:38 UTC