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.
- Base your Solution on Current Source Code, from the correct repository
First you must determine where the correct repository for the package you want to submit patches for resides. Each package has its own repository and submitting patches based on up to date source code, from the appropriate repository, via the appropriate method for the project, will get your patch adopted into the source package faster.
Once you've identified the correct repository, and located the files within it, which you need to modify, you should clone/checkout clean working copies of each, in preparation for making your changes.
- Keep an Unmodified Reference Copy of Every File you Intend to Modify
If you are working with the repository directly, the 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 patch set.
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 repository 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 repository 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.
- 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 working copy can be readily initialised by making `sandbox' your current directory, then executing the command:--
( cd current && tar cf - ) | ( cd working && tar xf - )
- Prepare a Test Case
If possible, you should provide a small test case 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 test case before you begin work on developing your patch; this way you can develop the test case 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 test case which serves to better illustrate idiosyncracies of your patch, rather than its correctness.
- 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 test case, 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 patch set.
- Prepare the PatchSet
A patch set should always be created in `diff -u' format, with a minimum of three lines of context, and procedure name annotations. 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 -pNaur current working > patchfile.diff
(This is convenient for you, because it captures all of your modifications into a single integrated patch set, 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
- 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. Create this as free standing text; do not include it within the scope of the diff defining the PatchSet; (however, it is permissible to include it within the diff file, as a block of free standing text preceding the actual diff content).
- 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 honor 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.
- Prepare a PatchSet Package for Submission
While the patch ticketing system 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, (if you did not include this within the diff file itself).
- 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.
- Submitting your Patch
At last, you are ready to submit your patch!
You should now proceed to the MinGW Issues Ticketing System and select the Create Ticket (or whatever new name SourceForge have adopted today) link, at the top left of the main window. Complete the displayed form, providing the appropriate information.:--
- 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 `Save' button, to complete your submission.