{: .no_toc }
{: .no_toc .text-delta }
Note: for ICU4C 49m2 or later, will require Doxygen 1.7.5.1 or later ( see ICU-8862 ). On Linux with debian style package management,
sudo apt-get install doxygen
Or, to install manually
configure --prefix /usr/local
” (to install into /usr/local/bin etc)make install
” with appropriate permission (perhaps “sudo make install
”.)doxygen --version
’ gives the correct number.Update the API documentation in all header files (.h file) to have correct @draft/@stable/@deprecated labels.
Update docmain.h
./configure
make doc
Follow instructions in tools/release/java/readme.txt to generate API status change report.
Make sure that ICU headers work with U_HIDE_DRAFT_API and other such switches.
Verify that U_DRAFT and U_STABLE match the @draft and @stable tags (same for other such pairs declaration macro vs. tag).
Update the API documentation to have correct @draft/@stable/@deprecated labels. See the User Guide, ICU Architectural Design, ICU API compatibility.
On ICU4J, run com.ibm.icu.dev.tool.docs.CheckTags (see file for instructions). This requires a JDK with javadoc available. The tool will need to change to reflect the release number to search for.
To check the API status changes, run the ant target “apireport” to generate the report since the previous official release.
Make sure @internal APIs are also marked as @deprecated:
* @internal * @deprecated This API is ICU internal only. @Deprecated
APIs previously introduced as @draft are reviewed for every new release. The current policy is to keep @draft status at least in one release cycle. For example, a new @draft API introduced in ICU 60 will be kept @draft in ICU 61. Then the API will be reviewed by ICU technical committee before ICU 62 release and the API can be promoted to @stable status.
Andy's method (from email 2019-sep-05):
$ ant draftAPIsTSV
$ ant apireport
This work is done in the root of icu4c:
source/configure
make doc
This work is done in the root of icu4j:
export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64
ant clean apireport
<icu4j_root>/APIChangeReport.html
and check it in.Once official release version is shipped, we need to keep API signature information file for next iteration. This is not done for milestone releases, only after the final official release.
Once APIs are frozen for a reference release, we should check in the API signature data file into the repository. The data file will be used for future API change report.
Note: This task is only necessary for reference releases, because we won't change public APIs in maintenance releases. The API signature file for an ICU4J version is generated and checked into trunk just before maint-xx branch is created for the major version, so we can keep track of API changes in maintenance releases of the major version (A maintenance release should have no API changes although).
In ICU4C, we want every (consecutive group of) @draft
API to be surrounded by #ifndef U_HIDE_DRAFT_API
. This allows users to -DU_HIDE_DRAFT_API
to make sure they don't use unstable API.
#ifndef U_HIDE_DRAFT_API /** @draft ICU 51 */ U_CAPI u_newFunction1(); /** @draft ICU 51 */ U_CAPI u_newFunction2(); #endif // U_HIDE_DRAFT_API
Same for @deprecated
& #ifndef U_HIDE_DEPRECATED_API .. #endif // U_HIDE_DEPRECATED_API
Same for @internal
& #ifndef U_HIDE_INTERNAL_API .. #endif // U_HIDE_INTERNAL_API
Same for @system
& #ifndef U_HIDE_SYSTEM_API .. #endif // U_HIDE_SYSTEM_API
Same for @obsolete
& #ifndef U_HIDE_OBSOLETE_API .. #endif // U_HIDE_OBSOLETE_API
For more details (and cautions) see the Coding Guidelines section C/C++ Hiding Un-@stable APIs.
a) For each of these API status tags, for each API that is tagged with it, verify that the API is surrounded by the appropriate #ifndef..#endif.
Note: It is best to not use one single guard for APIs with different ICU versions, since they will become stable and thus lose their guards at different times. Use one #ifndef..#endif guard per API status and ICU version.
b) For each of these U_HIDE_..._API guards, verify that it only and exactly surrounds APIs with the corresponding status tag. In particular, make sure that U_HIDE_DRAFT_API does not surround (newly) @stable API.
We don't have tools for this. One approach is to use “grep” or similar on the public common, i18n, io header files. Use grep options like -A 3, -B 2 and -C 3 for context After, Before, and Around the matching line. A better approach if you have the tools available is to use a programming-oriented text editor that can do (a) powerful regex search across (b) multiple files in several specified directories, and (c) display the matched lines in context such that (d) they or their context can be edited in place; an example of such a tool on macOS is BBEdit. This permits a comprehensive search using an expression such as “(U_HIDE_[A-Z_]+)|(@draft)|(@deprecated)|(@obsolete)|(@system)|(@internal)|(@preview)” which permits relatively easy checking for correct enclosure of status tags in conditionals.
As part of this, you may need to run side searches, for example to verify that no conditionalized type, function or value is used by an unconditionalized portion of a header file.
There is no magic bullet; however you carry out this step, it will require several hours of going through the grep/regex results and manually checking for correct enclosure, checking that conditionalized values are not needed elsewhere, etc.
Ignore this step for ICU49 and later. In ICU 49 and above, these header files and the gendraft/genheaders.pl tool are gone. (Ticket ICU-8571)
Instructions for ICU4C 4.8.x and earlier:
cd source/tools/gendraft ; make install-headers
Run the ICU4J versus JDK API comparison tool against the target JDK (anything that will come out before our next release, basically) with the tool com.ibm.icu.dev.tool.docs.ICUJDKCompare and make sure ICU4J adequately covers the JDK API for the classes we replicate.
Build the API documentation pages for the new release. Run Doxygen to create the javadoc files. Create icu4c-X_X_X-docs.zip
Note: for ICU4C 49m2 or later, requires Doxygen 1.7.5.1 or later ( see ICU-8862 )
make doc-searchengine
cd <path>/icu4c/source/doc/html/
zip /tmp/icu4c641 * # '641' needs to be replaced by the respective release label.
DRAFT:
Follow directions in How to update ICU docs
a. First, bring main branch of icu-docs fork up to date.
b. Copy the zip file to personal fork of icu-docs in apidoc/released/icu4c (or dev if not a release)
c. Unzip the file, replacing all documentation
d. Remove the zip file
e. `git add .`
f. `git commit -m “ICU- Update ICU4C API reference docs for XX.Y”
Example: “ICU-21546 Update ICU4C API reference docs for 69.1”
g. `git push origin main`
h. Create Pull Request at personal github fork for icu-docs from main into unicode-ort/icu-docs main branch
i. Request review
Note: This is also referenced below ‘Upload API documentations’ for how to make the API docs public.
Note: JCite must be installed for building ICU4J documentation: http://site.icu-project.org/setup/java/ant#TOC-Building-ICU4J-API-Reference-Document-with-JCite
Build the API documentation pages for the new release:
ant releaseDocs
Note: JCite must be installed for building ICU4J documentation: http://site.icu-project.org/setup/java/ant#TOC-Building-ICU4J-API-Reference-Document-with-JCite
Use the release target
ant releaseVer
which generate all release files.
See ‘Upload API documentations’ below for how to make the API docs public.
See https://unicode-org.github.io/icu-docs/HOWTO-Update.html for instructions to upload to https://unicode-org.github.io/icu-docs/
If there are any last second changes: