How to contribute to ICU


Why Contribute?

ICU is an open source library that is a de-facto industry standard for internationalization libraries. Our goal is to provide top of the line i18n support on all widely used platforms. By contributing your code to the ICU library, you will get the benefit of continuing improvement by the ICU team and the community, as well as testing and multi-platform portability. In addition, it saves you from having to re-merge your own additions into ICU each time you upgrade to a new ICU release.

Paperwork

Starting with ICU 58, ICU is a project of the Unicode® Consortium and the ICU Project Management Committee is a Unicode Technical Committee, the ICU-TC. ICU will continue to be released under the Unicode open source license, which is similar to the old ICU license. For more details, see the Unicode announcement.

For contributions — bug fix patches, one-time feature additions, or ongoing work as a team member — please sign the Unicode CLA; instructions are at the bottom of the ICU Trac "new ticket" page. Signing it once per person or organization is sufficient for future contributions.

For one-time patches or for occasional, limited changes, you could check out ICU code anonymously (use http:// rather than svn+ssh:// repository addresses), make the changes, and attach a patch file ("svn diff" in the root of the ICU source tree & redirect the output into a patch file) to an ICU Trac ticket.

If you want to join the team, then please contact us. Once everything is agreed, the ICU team gives you an ICU server account for svn write access, and an ICU Trac account for ticket (bugs/features) management.

General Contribution Requirements

We will be glad to take a look at the code you wish to contribute to ICU. We cannot guarantee that the code will be included. Contributions of general interest and written according to the following guidelines have a better chance of becoming a part of ICU.

For any significant new functionality, contact the ICU development team through the icu-design mailing list first, and discuss the features, design and scope of the possible contribution. This helps ensure that the contribution is expected and will be welcome, that it will fit in well with the rest of ICU, and that it does not overlap with other development work that may be underway.

While you are considering contributing code to ICU, make sure that the legal terms (see Legal Issues (§) below) are acceptable to you and your organization.

Here are several things to keep in mind when developing a potential contribution to the ICU project:

  1. ICU has both C/C++ and Java versions. If you develop in one programming language, please either provide a port or make sure that the logic is clear enough so that the code can be reasonably ported. We cannot guarantee that we will port a contribution to the other library.

  2. Before implementation, read and understand ICU's coding guidelines . Contributions that require too much adaptation to be included in the ICU tree will probably wait for a long time.

  3. During implementation, try to mimic the style already present in the ICU source code.

  4. Always develop the code as an integral part of the library, rather than an add-on.

  5. Always provide enough test code and test cases. We require that our APIs are 100% tested and that tests cover at least 85% of the ICU library code. Make sure that your tests are integrated into one of ICU's test suites (cintltst and intltest for ICU4C and com.ibm.icu.dev.test classes in ICU4J). New tests and the complete test suite should pass.

  6. Compile using the strictest compiler options. Due to ICU's multi-platform nature, warnings on some platforms may mean disastrous errors on other platforms. This can be enabled for C++ by using the --enable-strict configure option on any platform using the gcc or clang compilers.

  7. Test on more than one platform. For ICU4C, it is good to combine testing on Windows with testing on Linux, Mac OS X or another Unix platform. It is always good to try to mix big and little endian platforms. For ICU4J, test using both Oracle's and IBM's JDKs and/or on Android.

  8. Each contribution should contain everything that will allow building, testing and running ICU with the contribution. This usually includes: source code, build files and test files.

Team

We have several mailing lists. Contributors should at least subscribe to the icu-design mailing list, and we also have a team-internal list that you should get added to.

We meet once a week by phone. See the agenda & meeting minutes.

Understand ICU

Setup

Subversion setup for ICU developers: http://site.icu-project.org/setup/subversion

Eclipse and other setup: http://site.icu-project.org/setup

As a beginner, please work in branch for all but trivial changes, and get your changes reviewed before merging them onto the trunk.

Trac Tickets

We use Trac tickets to track bugs, feature requests and tasks. All new tickets are reviewed and assigned by the committee, normally during our weekly phone meeting, before the code is changed.​ (Sometimes there is a backlog and it takes more than a week; some urgent tickets are reviewed on the team mailing list.) See also the ticket life cycle page.

Significant/disruptive changes should be discusses on the icu-design list or on the team-internal list.

API changes must be proposed on the icu-design list, see the API Proposal Email Template.

Proposed changes will be discussed at the ICU meeting that follows at least a week later. Proposals are frequently modified during email and in-meeting discussion. Please do not "jump the gun" unless you are very confident your proposal will go through as-is, or be prepared to revert your changes.

Code reviews

See, well, Code reviews.

Welcome

... and thanks for contributing!
Comments