How can I help out?

This document deals with contributions to the Cygwin DLL and Cygwin-specific utilities*. Although the space and internet connection for this site have been paid for by Red Hat, the vast majority of the time for this project is volunteer time, including the time spent by Red Hat employees. Volunteer time is always in short supply, so if you are thinking about contributing, rest assured that your efforts will be welcome.

Contributions to other packages in the Cygwin distribution are also welcome and some of the principles involved are the same. However, most of the specific instructions here will not be applicable to utilities like apache, bash, gawk, etc., which are generally found in linux releases. If you have a patch for any of those, send it along to the cygwin mailing list and the appropriate package maintainer will respond. If you want to contribute a package that is not currently part of the Cygwin distribution, look here.

If you are looking to donate money to cygwin developers then check out the donations page.

Two other important cygwin components are also not covered by the guidelines set forth on this page. The cygwin setup utility and the newlib library (used by cygwin for some common "libc"-like functions) also have different contribution rules. See their project pages for more information.

Building the development version of Cygwin

The code corresponding to cygwin1.dll is mostly in the winsup directory with additional code coming from newlib/libc and newlib/libm. Any changes you make should be to the current development sources. This makes it much easier to integrate your changes once they're completed and tested. Note that the current Git tree should compile, but it should always be assumed to be unstable since it contains potentially untested, experimental code.

Build instructions are included in the FAQ under "How do I build Cygwin on my own?".

Basically, just clone the newlib-cygwin Git repository as mentioned on the Cygwin Git page.

Before you get started

Once you've checked out the sources, you will be able to avail yourself of the "how*" files in the winsup/cygwin directory. These are developer-written files which summarize various techniques involved in cygwin design. You should familiarize yourself with their content before making changes to the subsystems that they describe.

If your change is going to be a significant one in terms of the size of your code changes, be aware that for changes to all source files under the "winsup" directory you will have to license your code changes under the 2-clause BSD license before we can include your changes in the main source tree. (This is necessary for the next few years so that Red Hat can meet its continuing obligations to Cygwin buyout license customers while Cygwin transitions away from this licensing model.).

To do this, just make a public statement that you provide your patches to the Cygwin sources under the 2-clause BSD license.

You can do that with your first patch submission. After your first patch has been approved and applied, your name and email address will be added to the new winsup/CONTRIBUTORS file.

For the wording of the 2-clause BSD license, see the winsup/CONTRIBUTORS file in the Cygwin git repository.

If you already have a Cygwin Copyright Assignment signed and submitted, you can ignore this procedure. If you're not sure if you already signed the Copyright Assignment, see the list of signees in the winsup/CONTRIBUTORS file.

Finally, before you start modifying anything for real, you should probably join the cygwin-developers mailing list and send it mail describing what you want to do and how you want to do it so you don't waste time working on something we can't integrate. This also allows us to keep track of what's being worked on so efforts aren't duplicated.

It should go without saying but when you start coding your change, make sure that you adhere to the brace, indentation, and whitespace style of the surrounding code. For the most part, that means following the GNU coding standards but some parts of the code which have been imported from other sources use other styles. Just pay close attention to the formatting of the surrounding code and don't, e.g., add K&R style coding to a file which uses GNU formatting.

If you want to keep track of who's doing what to the sources, you can subscribe to the cygwin-cvs and newlib-cvs mailing lists using the standard subscription techniques employed for the other mailing lists.

When you have finalized your changes

Once you've finished making and testing your changes, send your patches to the cygwin-patches mailing list in git format-patch format.

As an example, if you have modified several files in /oss/newlib-cygwin/winsup, then do the following in bash:

      [hack, hack, hack]
      git add
      git commit
      [hack, hack, hack]
      git add
      git commit
      git format-patch [--cover-letter]

This will produce files with all of your changes newer than origin, making it easy for someone to review and, if you don't have write access, push. Give them a final once-over. Ideally you include a good description of your change with details what it does, how it works, what bug it fixes (if any) and generally lend a hand to readers of the git logs. Adding URLs to mailing list postings referencing the problem your patch solves might be a good idea, too.

Patchsets with smaller, self-contained patches are preferred over a single, huge patch. Add a cover letter (--cover-letter option) if you're sending a patch series to simplify discussing it on the mailing list.

If you're satisfied with the patch and the log message, send the patches as they got created by git format-patch. The git send-email command will usually do the right thing:

      git send-email --to="cygwin-patches@cygwin.com" <format-patch-files>

Note that you must be subscribed to cygwin-developers and cygwin-patches to send email to those lists.

Please feel free to ask questions about any of this. We would love it if more people made useful contributions -- this can be one of the big advantages of free software; we all benefit from everyone else's work as well as our own.

What needs doing

You can get a good idea of the current bugs and problem areas by browsing the cygwin mailing list archives. In addition, check out the API calls portion of the FAQ and look for references to unimplemented functions.

Remember that the cygwin-developers and cygwin-patches mailing lists are intended only for people who are serious about augmenting the cygwin DLL. These lists are not intended as a vehicle for getting general cygwin questions answered, for announcing ports of any utilities, or for providing patches for anything other than the files in the "winsup" directory. And, again, you will first have to join the lists before you are able to send email.

(If you just want to send email to the cygwin-patches mailing list without receiving email you can send email to cygwin-patches-allow-subscribe at cygwin dot com. This will allow you to send email to the list without receiving any of the email traffic. Be advised, however, that you may miss some messages about your patch if you do this.)

* Cygwin-specific utilities are any executable or shared libraries distributed in the cygwin distribution tar file, i.e., those files that are generated from the winsup/{cygwin,cygserver,utils} source directories.