mirror of
https://github.com/unicode-org/icu.git
synced 2025-04-07 06:25:30 +00:00
ICU-21404 Migrate various documents from Google Sites pages to Markdown.
Includes: - https://sites.google.com/site/icusite/processes/release/tasks/* - https://sites.google.com/site/icusite/processes/uni-up Some links fixed, copyright notices added, filenames improved, Sidebar navigation links to the new pages, but needs some further improvements. Updated /trac/ticket/ links, and /trac/changeset/ links where I could find the corresponding git commit. Also tweaked userguide/dev/editing.md to clarify 'root directory'. Apply branch rename: s/master/main/.
This commit is contained in:
Hugo van der Merwe
parent
121dbe8364
commit
03927878f8
23 changed files with 3257 additions and 3 deletions
1
.gitignore
vendored
1
.gitignore
vendored
|
|
@ -62,6 +62,7 @@ lib/
|
|||
!tools/cldr/lib
|
||||
out/
|
||||
release/
|
||||
!docs/processes/release/
|
||||
tmp/
|
||||
x64/
|
||||
x86/
|
||||
|
|
|
|||
BIN
docs/processes/release/tasks/NexusRepoMan.png
Normal file
BIN
docs/processes/release/tasks/NexusRepoMan.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 69 KiB |
143
docs/processes/release/tasks/announce.md
Normal file
143
docs/processes/release/tasks/announce.md
Normal file
|
|
@ -0,0 +1,143 @@
|
|||
---
|
||||
layout: default
|
||||
title: Announcements
|
||||
parent: Release & Milestone Tasks
|
||||
grand_parent: Contributors
|
||||
nav_order: 10
|
||||
---
|
||||
|
||||
<!--
|
||||
© 2021 and later: Unicode, Inc. and others.
|
||||
License & terms of use: http://www.unicode.org/copyright.html
|
||||
-->
|
||||
|
||||
# Announcements
|
||||
{: .no_toc }
|
||||
|
||||
## Contents
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
1. TOC
|
||||
{:toc}
|
||||
|
||||
---
|
||||
|
||||
## First milestone/candidate for a release
|
||||
|
||||
We write drafts of announcements in the ["ICU announcements" Google
|
||||
doc](https://docs.google.com/document/d/1rSVKZaus2K3rF66bMfDjYZnA2KTSJZUBz4C58GQMHsQ/edit).
|
||||
|
||||
When there is no section yet for the upcoming release, then copy the whole
|
||||
section from one of the previous two full releases and adjust the version
|
||||
numbers everywhere in the copied headings and text.
|
||||
|
||||
### Announcement for a release candidate
|
||||
|
||||
Adjust the release candidate announcement subsection with a very brief summary
|
||||
gleaned from the download page.
|
||||
|
||||
Share the draft as a link to the doc heading with the ICU team, invite comments
|
||||
and edits.
|
||||
|
||||
When ready, send to the mailing lists as indicated in the doc. Make sure to use
|
||||
bcc as noted for the "announce" lists.
|
||||
|
||||
### Announcement for a new major version
|
||||
|
||||
Adjust the final-release announcement subsection with a very brief summary
|
||||
gleaned from the download page. Adjust the blog & tweet texts as well.
|
||||
|
||||
Share the draft as a link to the doc heading with the ICU team, invite comments
|
||||
and edits.
|
||||
|
||||
Share the draft as a link with the Unicode editorial committee, invite comments,
|
||||
discuss, adjust as agreed.
|
||||
|
||||
When ready, send to the mailing lists as indicated in the doc. Make sure to use
|
||||
bcc as noted for the "announce" lists.
|
||||
|
||||
Notify Rick McGowan for the Unicode blog posting and Ken Lunde for tweeting.
|
||||
|
||||
Notify Ken Whistler (Unicode) to update the ICU version & date on
|
||||
<https://www.unicode.org/releases/>
|
||||
|
||||
Put a News item on the ICU project site.
|
||||
|
||||
### Announcement for a maintenance update
|
||||
|
||||
Same as for a release candidate, but start by copying the section for the last
|
||||
maintenance update in the doc.
|
||||
|
||||
## Update the reference for ICU in the external sites
|
||||
|
||||
**For freshmeat.net**
|
||||
|
||||
1. <http://www.freshmeat.net/>
|
||||
2. Login under the correct account.
|
||||
3. I usually search for: icu unicode
|
||||
4. Click on the project returned
|
||||
5. Under the 'project' drop down, choose 'Add release'
|
||||
6. We have (thankfully) only one branch of development- choose Default
|
||||
7. Release info
|
||||
* release focus: Choose the one which best fits
|
||||
* Version
|
||||
* Changes: be VERY brief, and include links if needed.
|
||||
Please read the other ICU4C/ICU4J updates to get an idea for how we are
|
||||
wording these. DO NOT use bulleted lists. DO use short 'sentences'.
|
||||
Remember they can go to the release list and/or bug DB for the full
|
||||
scoop!
|
||||
Put the URL to the 'release notes' (i.e.
|
||||
http://oss.software.ibm.com/icu/download/(version)/ ) in the changes
|
||||
list.
|
||||
* tar/gz, zip: Put the FULL URLs to the actual files, here
|
||||
* Changelog: Leave BLANK. This is for a single page of ALL release changes
|
||||
(Actually: http://oss.software.ibm.com/icu/download/ fits this fairly
|
||||
well.)
|
||||
* License - leave at MIT/X
|
||||
* mailing list: I set this to the main mailing list page.
|
||||
(http://oss.software.ibm.com/icu/archives/)
|
||||
Click 'go on..'
|
||||
8. PREVIEW.
|
||||
Very important- Check:
|
||||
* SPELLING
|
||||
* links!!!!! Make sure they go where we want
|
||||
* accuracy - version number is OK?
|
||||
Remember that this is an important PR face for ICU4C and ICU4J.
|
||||
9. Submit!
|
||||
|
||||
That's it. Submissions take some time (<24 hrs) to go on. I guess they check the
|
||||
accuracy as well- not sure here. (Steven Loomis, 2001-06-14)
|
||||
|
||||
**Other sites**:
|
||||
|
||||
[slashdot](http://slashdot.org/), [newsforge](http://newsforge.com/),
|
||||
[developerWorks unicode zone](http://www.ibm.com/developerworks/unicode/),
|
||||
[developerWorks open-source
|
||||
zone](http://www.ibm.com/developerworks/opensource/), [developerWorks java
|
||||
zone](http://www.ibm.com/developerworks/java/) (send email to `dWnews <at>
|
||||
us.ibm.com`)
|
||||
|
||||
[ICU sourceforge News](http://sourceforge.net/projects/icu) - login here, go to
|
||||
News, Admin, and submit a news item as an administrator.
|
||||
|
||||
---
|
||||
|
||||
#### LanguageTech Net News (tm)
|
||||
|
||||
"LanguageTech Net News" features the latest news for language technology and
|
||||
multilingual computing. It is prepared from materials compiled and maintained by
|
||||
the research editors at "[MultiLingual Computing &
|
||||
Technology](http://www.multilingual.com/)" and the Language Technology Research
|
||||
Center.
|
||||
|
||||
Press releases and submissions are always welcomed and encouraged. Please send
|
||||
e-mail to [news@multilingual.com](mailto:news@multilingual.com), faxes to
|
||||
208-263-6310 and postal mail to MultiLingual Computing, Inc., 319 North First
|
||||
Avenue, Sandpoint, ID 83864 USA, or call 208-263-8178.
|
||||
|
||||
To view archived issues of "LanguageTech Net News" visit
|
||||
<http://www.multilingual.com/>.
|
||||
|
||||
To subscribe to "LanguageTech Net News" go to
|
||||
<http://www.multilingual.com/multilingualpress/> or send an e-mail to
|
||||
[news-l-subscribe@multilingual.com](mailto:news-l-subscribe@multilingual.com).
|
||||
115
docs/processes/release/tasks/build.md
Normal file
115
docs/processes/release/tasks/build.md
Normal file
|
|
@ -0,0 +1,115 @@
|
|||
---
|
||||
layout: default
|
||||
title: Build Updates
|
||||
parent: Release & Milestone Tasks
|
||||
grand_parent: Contributors
|
||||
nav_order: 30
|
||||
---
|
||||
|
||||
<!--
|
||||
© 2021 and later: Unicode, Inc. and others.
|
||||
License & terms of use: http://www.unicode.org/copyright.html
|
||||
-->
|
||||
|
||||
# Build Updates
|
||||
{: .no_toc }
|
||||
|
||||
## Contents
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
1. TOC
|
||||
{:toc}
|
||||
|
||||
---
|
||||
|
||||
## Regenerate configure
|
||||
|
||||
Don't forget to re-run and check in the configure file along with configure.in.
|
||||
This is normally supposed to be done when configure.in or aclocal.m4 are
|
||||
modified. It also should be done whenever the version numbers change in
|
||||
**uvernum.h**
|
||||
|
||||
On a Linux system,
|
||||
|
||||
```sh
|
||||
cd icu4c/source
|
||||
autoconf
|
||||
```
|
||||
|
||||
Review the changes to configure, most commonly just an updated ICU version
|
||||
number. Sometimes there are differences due to different versions of the
|
||||
autoconf tool being used.
|
||||
|
||||
## Update urename.h
|
||||
|
||||
Update urename.h to catch all possible ICU4C library exports (especially on
|
||||
non-Windows systems that tend to ignore export qualifiers). See
|
||||
[icu4c/source/tools/genren/README](https://github.com/unicode-org/icu/blob/main/icu4c/source/tools/genren/README).
|
||||
|
||||
Diff the new one with the previous one; there are typically a few bad #defines
|
||||
in there.
|
||||
|
||||
You are looking to make sure that the defines all are correct exported symbols
|
||||
and that the Perl script hasn't inadvertently grabbed extraneous text. Each of
|
||||
the defines should be of the format "uxxxx_NamingConvention". If not then you
|
||||
need to determine if it's a script issue or a poorly named method.
|
||||
|
||||
Also, please look out for this type of message: "\***\*\* WARNING Bad namespace
|
||||
(not 'icu') on ShoeSize::ShoeSize()**" - it probably means that there is a class
|
||||
not defined inside the "icu" namespace. Consider adding **U_NAMESPACE_BEGIN**
|
||||
and **U_NAMESPACE_END** around the class and member definitions.
|
||||
|
||||
## Update the pool bundles
|
||||
|
||||
*Obsolete for ICU 64+*: The pool bundles are no longer checked in. Instead,
|
||||
they are built on the fly. (And smaller if the data is filtered.)
|
||||
|
||||
The locale data resource bundles use pool.res bundles (one per bundle tree) for
|
||||
sharing most of their resource table key strings. We should update the pool
|
||||
bundles once per release, or when we get new data from CLDR, or change the tree
|
||||
or key structure, to capture the changing set of key strings.
|
||||
|
||||
1. Build ICU4C
|
||||
2. Check the date and size of the old pool bundles, for comparison later
|
||||
1. `~/icu/mine/src$ find icu4c -name 'pool.res' -exec ls -l '{}' \;`
|
||||
3. Temporarily modify the data makefile: s/usePoolBundle/writePoolBundle/
|
||||
1. If you are not on Windows, you probably need to make other changes to
|
||||
the Makefile as well. See
|
||||
[ICU-8101](https://unicode-org.atlassian.net/browse/ICU-8101) (contains
|
||||
a data/Makefile patch; use the latest version there)
|
||||
2. I like to make a copy the Makefile, then change it, save that for
|
||||
possible reuse, and later copy the original back.
|
||||
3. Try to patch it in rather than redoing it manually:
|
||||
`~/icu/mine/bld/icu4c/data$ patch -p0 <
|
||||
~/Downloads/Makefile-writePoolBundle.patch`
|
||||
4. Rebuild the data (make sure it actually gets rebuilt: cd data, make clean,
|
||||
make)
|
||||
5. Copy all of the pool.res files like this
|
||||
1. Linux ICU 63, from inside the build output's data directory:
|
||||
2. ICUDT=icudt63l
|
||||
3. cp out/build/$ICUDT/pool.res ../../../src/icu4c/source/data/locales
|
||||
4. cp out/build/$ICUDT/lang/pool.res ../../../src/icu4c/source/data/lang
|
||||
5. cp out/build/$ICUDT/region/pool.res
|
||||
../../../src/icu4c/source/data/region
|
||||
6. cp out/build/$ICUDT/zone/pool.res ../../../src/icu4c/source/data/zone
|
||||
7. cp out/build/$ICUDT/curr/pool.res ../../../src/icu4c/source/data/curr
|
||||
8. cp out/build/$ICUDT/unit/pool.res ../../../src/icu4c/source/data/unit
|
||||
6. Double-check the date and size of the old pool bundles. Sizes are usually a
|
||||
few % higher than before, due to increased CLDR data.
|
||||
7. Revert the data makefile change (copy the original back, if you kept a copy)
|
||||
8. Rebuild the data (make sure it actually gets rebuilt: make clean, make)
|
||||
9. Build ICU4C & run tests
|
||||
10. Rebuild the ICU4J data .jar files
|
||||
1. See
|
||||
[icu4c/source/data/icu4j-readme.txt](https://github.com/unicode-org/icu/blob/main/icu4c/source/data/icu4j-readme.txt)
|
||||
2. And/or see "update Java data files" in
|
||||
[icu4c/source/data/unidata/changes.txt](https://github.com/unicode-org/icu/blob/main/icu4c/source/data/unidata/changes.txt)
|
||||
|
||||
If there are new bundle trees that should use pool.res files (like the "unit"
|
||||
tree in ICU 54 ticket
|
||||
[ICU-11092](https://unicode-org.atlassian.net/browse/ICU-11092)), then first
|
||||
modify the data makefiles (Windows and Linux) to add the new pool.res to the
|
||||
appropriate file lists and initially add --writePoolBundle which at the end also
|
||||
needs to be turned into --usePoolBundle. Or, simpler, initially copy (svn cp)
|
||||
the parent tree's pool bundle, and update it later (maybe during release task
|
||||
work).
|
||||
24
docs/processes/release/tasks/copy-shared-tests.md
Normal file
24
docs/processes/release/tasks/copy-shared-tests.md
Normal file
|
|
@ -0,0 +1,24 @@
|
|||
---
|
||||
layout: default
|
||||
title: Copy Shared Tests
|
||||
parent: Release & Milestone Tasks
|
||||
grand_parent: Contributors
|
||||
nav_order: 40
|
||||
---
|
||||
|
||||
<!--
|
||||
© 2021 and later: Unicode, Inc. and others.
|
||||
License & terms of use: http://www.unicode.org/copyright.html
|
||||
-->
|
||||
|
||||
# Copy Shared Tests
|
||||
|
||||
Certain tests are structured so that they can be shared between CLDR and ICU.
|
||||
That allows the tests to be run in CLDR earlier in the development process. The
|
||||
tests include:
|
||||
|
||||
* LocaleMatcherTest
|
||||
* TransformTest (to be cleaned up)
|
||||
|
||||
Copy all of these from CLDR to ICU, and sanity check the differences, then check
|
||||
in.
|
||||
405
docs/processes/release/tasks/docs.md
Normal file
405
docs/processes/release/tasks/docs.md
Normal file
|
|
@ -0,0 +1,405 @@
|
|||
---
|
||||
layout: default
|
||||
title: APIs & Docs
|
||||
parent: Release & Milestone Tasks
|
||||
grand_parent: Contributors
|
||||
nav_order: 20
|
||||
---
|
||||
|
||||
<!--
|
||||
© 2021 and later: Unicode, Inc. and others.
|
||||
License & terms of use: http://www.unicode.org/copyright.html
|
||||
-->
|
||||
|
||||
# APIs & Docs
|
||||
{: .no_toc }
|
||||
|
||||
## Contents
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
1. TOC
|
||||
{:toc}
|
||||
|
||||
---
|
||||
|
||||
## Update API status comments
|
||||
|
||||
### ICU4C
|
||||
|
||||
1. **Note: for ICU4C 49m2 or later, will require Doxygen 1.7.5.1 or later (
|
||||
see** [ICU-8862](https://unicode-org.atlassian.net/browse/ICU-8862) **).**
|
||||
On Linux with debian style package management,
|
||||
|
||||
`sudo apt-get install doxygen`
|
||||
|
||||
Or, to install manually
|
||||
1. To update Doxygen, first [download binary or source release
|
||||
here](http://doxygen.org/download.html#latestsrc)
|
||||
2. Unpack the release, and run something like<br>
|
||||
"`configure --prefix /usr/local`" (to install into /usr/local/bin etc)<br>
|
||||
(Note for the binary release, 'configure' just builds an installer.)
|
||||
3. Run "`make install`" with appropriate permission (perhaps
|
||||
"`sudo make install`".)
|
||||
4. Verify that '`doxygen --version`' gives the correct number.
|
||||
|
||||
2. Update the API documentation in all header files (.h file) to have correct
|
||||
@draft/@stable/@deprecated labels.
|
||||
3. Update docmain.h
|
||||
4. ./configure
|
||||
5. make doc
|
||||
6. Follow instructions in
|
||||
[tools/release/java/readme.txt](https://htmlpreview.github.io/?https://github.com/unicode-org/icu/blob/main/tools/release/java/readme.txt)
|
||||
to generate API status change report.
|
||||
7. Make sure that ICU headers work with U_HIDE_DRAFT_API and other such
|
||||
switches.
|
||||
8. Verify that U_DRAFT and U_STABLE match the @draft and @stable tags (same for
|
||||
other such pairs declaration macro vs. tag).
|
||||
1. For example, on Linux:
|
||||
2. grep --recursive --include="\*.h" --exclude-dir=".svn" -e "@deprecated"
|
||||
-A 5 . > at-deprecated.txt
|
||||
3. grep --recursive --include="\*.h" --exclude-dir=".svn" -e "U_DEPRECATED"
|
||||
-B 5 -A 1 . > u_deprecated.txt
|
||||
4. Do this for draft, deprecated, obsolete, internal.
|
||||
5. For @stable, we either verify by cleaning up all others or we need to
|
||||
write a script.
|
||||
|
||||
### ICU4J
|
||||
|
||||
Update the API documentation to have correct @draft/@stable/@deprecated labels.
|
||||
See the [User Guide, ICU Architectural Design, ICU API
|
||||
compatibility](http://userguide.icu-project.org/design#TOC-ICU-API-compatibility).
|
||||
|
||||
On ICU4J, run
|
||||
[com.ibm.icu.dev.tool.docs.CheckTags](https://github.com/unicode-org/icu/blob/main/icu4j/tools/build/src/com/ibm/icu/dev/tool/docs/CheckTags.java)
|
||||
(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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Promote draft APIs to stable
|
||||
|
||||
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.
|
||||
|
||||
### **ICU4C**
|
||||
|
||||
Andy's method (from email 2019-sep-05):
|
||||
|
||||
* Creation of the promotion spreadsheet was done by hand. It's something of an
|
||||
iterative process.
|
||||
* Start by making a copy of the previous release spread sheet, to get the
|
||||
format, and probable entries for older @draft items that are perpetually
|
||||
being held back.
|
||||
* Do the API promotion - search the sources for @draft, and make a best guess
|
||||
at what to promote. Add entries to the spread sheet as you go. Note any
|
||||
items you're not sure about.
|
||||
* Run the API change report tool, see what looks inconsistent, fix up the
|
||||
sources and rerun as needed. Deleted functions will first show up here, and
|
||||
are added to the spread sheet.
|
||||
* Cross-check the API change report and the spread sheet.
|
||||
* The whole thing takes a bit of time to do.
|
||||
|
||||
### **ICU4J**
|
||||
|
||||
1. Create a new GitHub branch.
|
||||
2. Run next ant target: `$ ant draftAPIsTSV`
|
||||
3. This **ant** target generates a tab-separated values file at
|
||||
icu4j/out/draftAPIs.tsv.
|
||||
4. Import the TSV file to Google spread sheet - for example, [ICU4J 61 Draft
|
||||
API
|
||||
Promotion](https://docs.google.com/spreadsheets/d/135RDyY6cWKBBvNuVE9ne8HfsItZu_CvLh47hKjr3UqM/edit#gid=1384666589).
|
||||
* Create the spreadsheet in the shared ***ICU Projects*** folder.
|
||||
5. Review all APIs introduced in 2 releases ago or older. For example, 59 or
|
||||
older for ICU 61 release.
|
||||
* Any API added 2 or more releases ago is a candidate for promotion.
|
||||
* Newer APIs should be left in @draft state.
|
||||
6. Check each API entry has a corresponding approved API proposal. For example,
|
||||
[ICU 59 API proposal
|
||||
status](https://docs.google.com/document/d/12dHTG3e9WXb7C1Xdc2bcXE0BK8f6IoufoUAPcz4ZT2I/edit).
|
||||
Note: An API proposal might have been created before the API proposal doc
|
||||
version, so you may need to look at older version of API proposal status
|
||||
doc.
|
||||
7. Mark APIs proposed for promotion, and add note in the spread sheet.
|
||||
8. Update API comments in ICU4J source code. In this case, @draft is replaced
|
||||
with @stable (do not change ICU version, for example, "@draft ICU 59" will
|
||||
be changed to "@stable ICU 59").
|
||||
9. Run next ant target to generate an API change report html: `$ ant apireport`
|
||||
10. Review the report, sent the report file and the link of the spread sheet to
|
||||
ICU technical committee members for review.
|
||||
11. Once ICU TC approves the proposed change, create a pull request (PR), wait
|
||||
for review, and merge the branch into the main branch.
|
||||
|
||||
---
|
||||
|
||||
## Update the API Change Report
|
||||
|
||||
### ICU4C
|
||||
|
||||
This work is done in the root of icu4c:
|
||||
|
||||
1. Update the API documentation in all header files (.h file) to have correct
|
||||
@draft/@stable/@deprecated/@obsolete labels.
|
||||
2. Update docmain.h with additions or removals as needed.
|
||||
3. `source/configure`
|
||||
4. `make doc`
|
||||
5. Follow instructions in
|
||||
[tools/release/java/readme.txt](https://github.com/unicode-org/icu/blob/main/tools/release/java/readme.txt).
|
||||
|
||||
### ICU4J
|
||||
|
||||
This work is done in the root of icu4j:
|
||||
|
||||
1. Make sure JAVA_HOME is set to JDK 8. This report creation fails with JDK 11.
|
||||
For example, in Linux:
|
||||
* `export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64`
|
||||
2. Then run ant task "clean" and "apireport" at <icu4j_root>:
|
||||
* `ant clean apireport`
|
||||
3. Above will produce API change report file
|
||||
<code><icu4j_root>/<b>out</b>/icu4j_compare_xxx_yyy.html</code>
|
||||
4. Make sure there are any new doc tag errors are reported. (As of ICU 4.4,
|
||||
ArabicShaping constants do not have proper tags - otherwise, clean)
|
||||
5. Copy generated report file to `<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.
|
||||
|
||||
1. Run ant task "gatherapi" at <icu4j_root>
|
||||
2. Above will produce API signature information file
|
||||
<icu4j_root>/out/icu4jxx.api2.gz
|
||||
3. Copy icu4jxxapi2.gz to <icu4j_root>/tools/build and add it to the repository
|
||||
|
||||
---
|
||||
|
||||
## Check in API signature data file (ICU4J)
|
||||
|
||||
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.
|
||||
|
||||
1. Run ant task "gatherapi" at <icu4j_root>
|
||||
2. The output file icu4j<ver>.api3.gz is created in <icu4j_root>/out directory.
|
||||
3. Copy the output .gz file to <icu4j_root>/tools directory and check in the
|
||||
file to the repository.
|
||||
4. You may delete very old versions of the API signature files. Keeping 10
|
||||
versions to the latest should be good enough.
|
||||
|
||||
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).
|
||||
|
||||
---
|
||||
|
||||
## Verify that @draft is surrounded by #ifndef U_HIDE_DRAFT_API etc
|
||||
|
||||
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` & <code>#ifndef U_HIDE_<b>DEPRECATED</b>_API</code> ..
|
||||
`#endif // U_HIDE_DEPRECATED_API`
|
||||
|
||||
Same for `@internal` & <code>#ifndef U_HIDE_<b>INTERNAL</b>_API</code> ..
|
||||
`#endif // U_HIDE_INTERNAL_API`
|
||||
|
||||
Same for `@system` & <code>#ifndef U_HIDE_<b>SYSTEM</b>_API</code> ..
|
||||
`#endif // U_HIDE_SYSTEM_API`
|
||||
|
||||
Same for `@obsolete` & <code>#ifndef U_HIDE_<b>OBSOLETE</b>_API</code> ..
|
||||
`#endif // U_HIDE_OBSOLETE_API`
|
||||
|
||||
### Caution
|
||||
|
||||
* We cannot #ifndef-guard virtual methods because that makes the vtable
|
||||
incompatible.
|
||||
* // Cannot use #ifndef U_HIDE_DRAFT_API for the following draft method
|
||||
since it is virtual.
|
||||
* When you #ifndef-guard enum constants, normally the following unguarded ones
|
||||
(e.g., a _COUNT or _LIMIT) should retain the same numeric values as if the
|
||||
guard was absent.
|
||||
|
||||
<span style="background-color:yellow">For more details (and cautions) see the
|
||||
Coding Guidelines section [C/C++ Hiding Un-@stable
|
||||
APIs](http://userguide.icu-project.org/dev/codingguidelines#TOC-C-C-Hiding-Un--stable-APIs).</span>
|
||||
|
||||
### Task
|
||||
|
||||
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. <span style="background-color:yellow">One approach
|
||||
is to</span> 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. <span style="background-color:yellow">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.</span>
|
||||
|
||||
<span style="background-color:yellow">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.</span>
|
||||
|
||||
<span style="background-color:yellow">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.</span>
|
||||
|
||||
---
|
||||
|
||||
## Update udraft.h, usystem.h, uintrnl.h, uobslete.h and udeprctd.h
|
||||
|
||||
*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](https://unicode-org.atlassian.net/browse/ICU-8571))*
|
||||
|
||||
Instructions ***for ICU4C 4.8.x and earlier***:
|
||||
|
||||
1. make doc
|
||||
2. `cd source/tools/gendraft ; make install-headers`
|
||||
3. Double check the modified files in <icu>/source/common/unicode folder and
|
||||
commit.
|
||||
|
||||
---
|
||||
|
||||
## Compare ICU4J APIs with JDK
|
||||
|
||||
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](https://github.com/unicode-org/icu/blob/main/icu4j/tools/build/src/com/ibm/icu/dev/tool/docs/ICUJDKCompare.java)
|
||||
and make sure ICU4J adequately covers the JDK API for the classes we replicate.
|
||||
|
||||
---
|
||||
|
||||
## Build API documentations
|
||||
|
||||
### **ICU4C**
|
||||
|
||||
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](https://unicode-org.atlassian.net/browse/ICU-8862) )**
|
||||
|
||||
#### Steps:
|
||||
|
||||
1. Go to .../icu4c/source
|
||||
2. Generate the API document pages:<br>
|
||||
`make doc-searchengine`
|
||||
3. The generated API docs are in <path>/icu4c/source/doc/html/<br>
|
||||
`cd <path>/icu4c/source/doc/html/`
|
||||
4. Create a zip file, e.g.,<br>
|
||||
`zip /tmp/icu4c641 * # '641' needs to be replaced by the respective release label.`
|
||||
5. ~~Upload this zip file to the GitHub release page. For the live API docs, see below.~~
|
||||
|
||||
DRAFT:
|
||||
|
||||
5. Follow directions in [How to update ICU docs](https://unicode-org.github.io/icu-docs/HOWTO-Update.html)
|
||||
|
||||
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-<TICKET-NUMBER> Update ICU4C API reference docs for
|
||||
XX.Y"<br>
|
||||
Example: ["ICU-21546 Update ICU4C API reference docs for 69.1"](https://github.com/unicode-org/icu-docs/pull/25)
|
||||
|
||||
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](docs.md)' for how to make the API docs public.
|
||||
|
||||
### ICU4J
|
||||
|
||||
**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
|
||||
```
|
||||
|
||||
#### Alternative method:
|
||||
|
||||
**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.
|
||||
|
||||
* Upload the output files including icu4j-docs.jar to the release page first,
|
||||
* Then update the live API docs from the generated docs.jar.
|
||||
|
||||
See '[Upload API documentations](docs.md)' below for how to make the API docs public.
|
||||
|
||||
### Upload API documentations
|
||||
|
||||
See <https://unicode-org.github.io/icu-docs/HOWTO-Update.html> for instructions
|
||||
to upload to <https://unicode-org.github.io/icu-docs/>
|
||||
|
||||
---
|
||||
|
||||
### Update the Readme.html for GA
|
||||
|
||||
If there are any last second changes:
|
||||
|
||||
* Make sure to document especially items that affect software that is
|
||||
currently compiled with the previous version of ICU.
|
||||
* Update build/installation instructions as necessary.
|
||||
563
docs/processes/release/tasks/healthy-code.md
Normal file
563
docs/processes/release/tasks/healthy-code.md
Normal file
|
|
@ -0,0 +1,563 @@
|
|||
---
|
||||
layout: default
|
||||
title: Healthy Code
|
||||
parent: Release & Milestone Tasks
|
||||
grand_parent: Contributors
|
||||
nav_order: 50
|
||||
---
|
||||
|
||||
<!--
|
||||
© 2021 and later: Unicode, Inc. and others.
|
||||
License & terms of use: http://www.unicode.org/copyright.html
|
||||
-->
|
||||
|
||||
# Healthy Code
|
||||
{: .no_toc }
|
||||
|
||||
## Contents
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
1. TOC
|
||||
{:toc}
|
||||
|
||||
---
|
||||
|
||||
## Check for ClassID in new class hierarchies
|
||||
|
||||
Check that there are no "poor man's RTTI" methods in new class hierarchies.
|
||||
|
||||
After ICU 50: New class hierarchies should not declare getDynamicClassID() at
|
||||
all. UObject has a dummy implementation for it.
|
||||
|
||||
ICU 4.6..50: New class hierarchies used UOBJECT_DEFINE_NO_RTTI_IMPLEMENTATION.
|
||||
See Normalizer2 for an example declaration and implementation that satisfies the
|
||||
virtual-function override without adding new ClassID support.
|
||||
|
||||
We do need to keep and add "poor man's RTTI" in old classes, and in new classes
|
||||
extending existing class hierarchies (where parent classes have @stable RTTI
|
||||
functions). (For example, a new Format subclass.)
|
||||
|
||||
One easy way to check for this is to search through the API change report and
|
||||
look for "UClassID" or similar.
|
||||
|
||||
* Latest trunk report:
|
||||
[icu/icu4c/APIChangeReport.html](https://github.com/unicode-org/icu/blob/main/icu4c/APIChangeReport.html)
|
||||
* ~~The automated build system creates a new report:
|
||||
<https://cldr-build.unicode.org/jenkins/job/icu/job/icu-apidocs/>~~
|
||||
* Click "ICU4C API Change Report vs Latest"
|
||||
* Old: was http://bugs.icu-project.org/trac/build/icu4cdocs
|
||||
* Go into the latest successful build, the report is an attachment there.
|
||||
* Download the style sheet next to it:
|
||||
https://github.com/unicode-org/icu/blob/main/icu4c/icu4c.css
|
||||
|
||||
---
|
||||
|
||||
## ~~Check for non-ascii characters in ICU4C source files \[obsolete\]~~
|
||||
|
||||
~~Note: ICU4C and ICU4J source files are UTF-8. The ASCII check is no longer
|
||||
appropriate for them.~~
|
||||
|
||||
```sh
|
||||
cd icu4c/source
|
||||
find . \( -name "*.[ch]" -or -name "*.cpp" \) -exec grep -PHn [^[:ascii:]] {} \;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Check source files for valid UTF-8 and correct text file line endings
|
||||
|
||||
Verify that all source and text files in the repository have plain LF line
|
||||
endings.
|
||||
|
||||
To do this on Linux, In an up-to-date git workspace,
|
||||
|
||||
```sh
|
||||
cd icu/icu4c/source
|
||||
tools/icu-file-utf8-check.py # reports problems
|
||||
```
|
||||
|
||||
The same python script from the icu4c tools will also check icu4j
|
||||
|
||||
```sh
|
||||
cd icu/icu4j
|
||||
../icu4c/source/tools/icu-file-utf8-check.py
|
||||
```
|
||||
|
||||
To double-check the line endings, the following grep will find all text files
|
||||
containing \\r characters. Do not run from Windows, where \\r\\n line endings
|
||||
are expected.
|
||||
|
||||
```sh
|
||||
cd icu
|
||||
grep -rPIl "\r" *
|
||||
```
|
||||
|
||||
Even when run from Mac or Linux, some WIndows specific files (.bat, etc) will be
|
||||
found by this check. This is OK.
|
||||
|
||||
## ~~Check UTF-8 file properties \[obsolete\]~~
|
||||
|
||||
*Note: As of ICU 63, the project moved from svn to GitHub. SVN file properties
|
||||
are no longer relevant.*
|
||||
|
||||
<span style="color:red">**Note: As of ICU 59, ICU4C source files are UTF-8
|
||||
encoded, and have the svn mime-type property "text/plain;charset=utf-8". They
|
||||
must not have a BOM.**</span>
|
||||
|
||||
This is checked by the above task, *Check svn properties, valid UTF-8 and text
|
||||
file line endings.*
|
||||
|
||||
The bomfix.py script, formerly used for this task, must *not* be run over the
|
||||
ICU4C sources
|
||||
|
||||
<span style="color:red">**~~Note: This task is only applicable to ICU4C. ICU4J
|
||||
.java source files are encoded by UTF-8, but must be without UTF-8
|
||||
BOM.~~**</span>
|
||||
|
||||
~~Check that the following match: Files marked as UTF-8 vs. Files beginning with
|
||||
the UTF-8 signature byte sequence ("BOM").~~
|
||||
|
||||
~~Run:~~
|
||||
|
||||
<pre><code><s>cd {icu}/icu4c</s>
|
||||
<s>python ../tools/release/c/bomfix.py</s></code></pre>
|
||||
|
||||
---
|
||||
|
||||
## Clean up import statements
|
||||
|
||||
The Eclipse IDE provides a feature which allow you to organize import statements
|
||||
for multiple files. Right click on projects/source folders/files, you can select
|
||||
\[Source\] - \[Organize Imports\] which resolve all wildcard imports and sort
|
||||
the import statements in a consistent order. (Note: You may experience OOM
|
||||
problem when your run this for projects/folders which contain many files. In
|
||||
this case, you may need to narrow a selection per iteration.)
|
||||
|
||||
---
|
||||
|
||||
## Check library dependencies
|
||||
|
||||
***ICU 64+ (2019+): Done automatically by a build bot, at least in one of the
|
||||
two modes (debug/release), ok to skip as BRS task.***
|
||||
|
||||
We want to keep dependencies between .c/.cpp/.o files reasonable, both between
|
||||
and inside ICU's libraries.
|
||||
|
||||
On Linux, run
|
||||
[source/test/depstest/depstest.py](https://github.com/unicode-org/icu/blob/main/icu4c/source/test/depstest/dependencies.py),
|
||||
for example:
|
||||
```sh
|
||||
~/icu/mine/src/icu4c/source/test/depstest$ ./depstest.py ~/icu/mine/dbg/icu4c
|
||||
```
|
||||
|
||||
Do this twice: Once for a release build (optimized) and once for a debug build
|
||||
(unoptimized). They pull in slightly different sets of standard library symbols
|
||||
(see comments in dependencies.txt).
|
||||
|
||||
If everything is fine, the test will print "OK: Specified and actual
|
||||
dependencies match." If not...
|
||||
|
||||
*Get changes reviewed by others, including Markus; including changes in
|
||||
dependencies.txt, .py scripts, or ICU4C code.*
|
||||
|
||||
At first, the test will likely complain about .o files not listed in its
|
||||
dependencies.txt or, if files were removed, the other way around. Try to add
|
||||
them to groups or create new groups as appropriate.
|
||||
|
||||
As a rule, smaller groups with fewer dependencies are preferable. If public API
|
||||
(e.g., constructing a UnicodeString via conversion) is not needed inside ICU
|
||||
(e.g., unistr_cnv), make its library depend on its new group.
|
||||
|
||||
If the test prints "Info: group icuplug does not need to depend on platform"
|
||||
then the plug-in code is disabled, as is the default since ICU 56. Consider
|
||||
enabling it for dependency checking, but make sure to revert that before you
|
||||
commit changes!
|
||||
|
||||
There are usually other "Info" messages where the tool thinks that dependencies
|
||||
on system symbols are not needed. These are harmless, that is, don't try to
|
||||
remove them: They are needed or not needed based on the compiler flags used. If
|
||||
you remove them, then you will likely cause an error for someone with different
|
||||
flags. Also, in an unoptimized build you only get half as many info messages.
|
||||
You get more in an optimized build because more system stuff gets inlined.
|
||||
|
||||
The test might complain "is this a new system symbol?" We should be careful
|
||||
about adding those. For example, we must not call printf() from library code,
|
||||
nor the global operator new.
|
||||
|
||||
The test might complain that some .o file "imports
|
||||
icu_48::UnicodeString::UnicodeString(const char \*) but does not depend on
|
||||
unistr_cnv.o". This probably means that someone passes a simple "string literal"
|
||||
or a char\* into a function that takes a UnicodeString, which invokes the
|
||||
default-conversion constructor. We do not want that! In most cases, such code
|
||||
should be fixed, like in [changeset
|
||||
30186](http://bugs.icu-project.org/trac/changeset/30186). Only implementations
|
||||
of API that require conversion should depend on it; for example, group
|
||||
formattable_cnv depends on group unistr_cnv, but then nothing inside ICU depends
|
||||
on that.
|
||||
<!-- I did not find 30186 - I only found X-SVN-Rev's 30184 and 30188:
|
||||
https://github.com/unicode-org/icu/commit/b22717a642c2d416c56931efee61aa4ee386c027
|
||||
https://github.com/unicode-org/icu/commit/8cc8801c031f7e29b87d075ad39afd39dc4e95d6
|
||||
-->
|
||||
|
||||
---
|
||||
|
||||
## Verify proper memory allocation functions
|
||||
|
||||
Verify the following for library code (common, i18n, layout, ustdio). The
|
||||
requirement is for ICU's memory management to be customizable by changing
|
||||
cmemory.h and the common base class.
|
||||
|
||||
**Note:** The requirement remains. The techniques to fix issues are valid.
|
||||
***For testing**, see the section "Check library dependencies" above.*
|
||||
|
||||
* No raw malloc/free/realloc but their uprv_ versions.
|
||||
* All C++ classes must inherit the common base class UObject or UMemory
|
||||
* But not for mixin/interface classes (pure virtual, no data members, no
|
||||
constructors) because that would break the single-inheritance model.
|
||||
* Also not for pure-static classes (used for name scoping) declare but
|
||||
don't implement a private default constructor to prevent instantiation.
|
||||
* Simple struct-like C++ classes (and structs) that do not have
|
||||
constructors, destructors, and virtual methods, need not inherit the
|
||||
base class but must then be allocated with uprv_malloc.
|
||||
* All simple types (UChar, int32_t, pointers(!), ...) must be allocated with
|
||||
uprv_malloc and released with uprv_free.
|
||||
* For Testing that this is the case, on Linux
|
||||
* run the Perl script ICUMemCheck.pl. Follow the instructions in the
|
||||
script. The script is in in the ICU4C sources at
|
||||
source/tools/memcheck/ICUMemCheck.pl.
|
||||
* also, depstest.py will show an error message if the global operator new
|
||||
is used (see section about checking dependencies)
|
||||
* For testing that this is the case, on Windows:
|
||||
* Don't bother, as of Nov, 2004. Failures appear in many dozens of files
|
||||
from the mixin class destructors. Do the check on Linux. But, for
|
||||
reference, here are the old instructions.
|
||||
* Make sure that in `uobject.h` `UObject::new` and `delete` are
|
||||
defined by default. Currently, this means to grep to see that
|
||||
`U_OVERRIDE_CXX_ALLOCATION` is defined to 1 (in `pwin32.h` for
|
||||
Windows).
|
||||
* Check the \*.obj's for linkage to the global (non-UObject::)
|
||||
operators new/delete; see uobject.cpp for details.
|
||||
* Global `new` must never be imported. Global `delete` will be
|
||||
imported and used by empty-virtual destructors in interface/mixin
|
||||
classes. However, they are not called because implementation classes
|
||||
always derive from UMemory. No other functions must use global
|
||||
delete.
|
||||
* There are now (2002-dec-17) definitions in `utypes.h` for global
|
||||
new/delete, with inline implementations that will always crash.
|
||||
These global new/delete operators are only defined for code inside
|
||||
the ICU4C libraries (but must be there for all of those). See ticket
|
||||
#2581.
|
||||
* If a global new/delete is used somewhere, then change the class
|
||||
inheritance and/or use uprv_malloc/free until no global new/delete
|
||||
are used in the libraries (and the tests still pass...). See the
|
||||
User Guide Coding Guidelines for details.
|
||||
|
||||
---
|
||||
|
||||
## Run static code analysis tools
|
||||
|
||||
(Purify, Boundary Checker, valgrind...)
|
||||
|
||||
Make sure we fixed all the memory leak problems that were discovered when
|
||||
running these tools.
|
||||
|
||||
Build ICU with debug information. On Linux,
|
||||
|
||||
```sh
|
||||
runConfigureICU --enable-debug --disable-release Linux
|
||||
```
|
||||
|
||||
Run all of the standard tests under valgrind. For intltest, for example,
|
||||
|
||||
```sh
|
||||
cd <where ever>/source/test/intltest
|
||||
LD_LIBRARY_PATH=../../lib:../../stubdata:../../tools/ctestfw:$LD_LIBRARY_PATH valgrind ./intltest
|
||||
```
|
||||
|
||||
You can grab the command line for running the tests from the output from "make
|
||||
check", and then just insert "valgrind" before the executable.
|
||||
|
||||
---
|
||||
|
||||
## Check the code coverage numbers
|
||||
|
||||
Our goal is that all releases go out to the public with 100% API test and at
|
||||
least 85% code coverage.
|
||||
|
||||
---
|
||||
|
||||
## Test ICU4C headers
|
||||
|
||||
### Test ICU4C public headers
|
||||
|
||||
Testing external dependencies in header files:
|
||||
|
||||
(on Unixes) Prerequisite: Configure with --prefix
|
||||
(../icu4c/source/runConfigureICU Linux --prefix=/some/temp/folder) and do 'make
|
||||
install'. Then set the PATH so that the installed icu-config script can be
|
||||
found. (export PATH=/some/temp/folder/**bin**:$PATH)
|
||||
|
||||
Then go to the 'icu4c/test/hdrtst' directory (note: not 'source/test/hdrtst')
|
||||
and do 'make check'. This will attempt to compile against each header file
|
||||
individually to make sure there aren't any problems. Output looks like this, if
|
||||
no error springs up all is in order.
|
||||
|
||||
~~If a C++ file fails to compile as a C file, add it to the 'cxxfiles.txt'
|
||||
located in the hdrtst directory.~~
|
||||
|
||||
<span style="color:red">**As of ICU 65, the hdrtst is now run as part of the
|
||||
regular CI builds, and the C++ headers are now guarded with the macro
|
||||
"U_SHOW_CPLUSPLUS_API".**</span>
|
||||
|
||||
There is no longer any "cxxfiles.txt" file. Instead the public C++ headers are
|
||||
all guarded with the macro "U_SHOW_CPLUSPLUS_API" which is set to 1 by default
|
||||
if __cplusplus is defined. Users of ICU can explicitly set the macro before
|
||||
including any ICU headers if they wish to only use the C APIs. Any new public
|
||||
C++ header needs to be similarly guarded with the macro, though this should be
|
||||
caught in the CI builds for a pull-request before it is merged.
|
||||
|
||||
Run this test with all the uconfig.h variations (see below).
|
||||
|
||||
```sh
|
||||
ctest unicode/docmain.h
|
||||
ctest unicode/icudataver.h
|
||||
ctest unicode/icuplug.h
|
||||
```
|
||||
|
||||
### Test ICU4C internal headers
|
||||
|
||||
Run the following script straight from the source tree (from inside the "source"
|
||||
folder, not on the top level), no need to build nor install.
|
||||
|
||||
For a new release, also look for new tools and tests and add their folders to
|
||||
the script. You can ignore messages stating that no '\*.h' files were found in a
|
||||
particular directory.
|
||||
|
||||
The command line is simply
|
||||
|
||||
```sh
|
||||
~/git.icu/icu4c/source$ test/hdrtst/testinternalheaders.sh
|
||||
```
|
||||
|
||||
See https://unicode-org.atlassian.net/browse/ICU-12141 "every header file should
|
||||
include all other headers if it depends on definitions from them"
|
||||
|
||||
<span style="color:red">**As of ICU 68, the internal header test is now
|
||||
automated as part of Travis CI.**</span>
|
||||
|
||||
---
|
||||
|
||||
## Test uconfig.h variations
|
||||
|
||||
Test ICU completely, and run the header test (above) with:
|
||||
|
||||
1. **none** of the 'UCONFIG_NO_XXX' switches turned on (i.e., the normal case)
|
||||
2. **all** of the 'UCONFIG_NO_XXX' switches turned on (set to 1)
|
||||
3. For each switch, test once with **just** that one switch on. But note the
|
||||
exception regarding [UCONFIG_NO_CONVERSION test](healthy-code.md) below.
|
||||
|
||||
(See
|
||||
[common/unicode/uconfig.h](https://github.com/unicode-org/icu/blob/main/icu4c/source/common/unicode/uconfig.h)
|
||||
for more documentation.)
|
||||
|
||||
There is a script available which will automatically test ICU in this way on
|
||||
UNIXes, it lives in:
|
||||
[tools/release/c/uconfigtest.sh](https://github.com/unicode-org/icu/blob/main/tools/release/c/uconfigtest.sh).
|
||||
See docs at top of script for information.
|
||||
|
||||
<span style="background-color:yellow">When guard conditionals (e.g. #ifndef
|
||||
U_HIDE_INTERNAL_API) are removed because they cause header test failures, please
|
||||
note in the header file the reason that guard conditionals cannot be used in
|
||||
that location, or they will lkeiely be re-added in the future.
|
||||
|
||||
---
|
||||
|
||||
## Test C++ Namespace Use
|
||||
|
||||
Verify that ICU builds without enabling the default use of the ICU namespace. To
|
||||
test on Linux,
|
||||
|
||||
```sh
|
||||
./runConfigureICU Linux CXXFLAGS="-DU_USING_ICU_NAMESPACE=0"
|
||||
make check
|
||||
```
|
||||
|
||||
Any problems will show up as compilation errors.
|
||||
|
||||
When definitions outside the ICU C++ namespace refer to ICU C++ classes, those
|
||||
need to be qualified with "`icu::`", as in "`icu::UnicodeString`". In rare
|
||||
cases, a C++ type is also visible in C code (e.g., ucol_imp.h has definitions
|
||||
that are visible to cintltst) and then we use `U_NAMESPACE_QUALIFIER` which is
|
||||
defined to be empty when compiling for C.
|
||||
|
||||
The automated build system should have a machine that sets both
|
||||
`-DU_USING_ICU_NAMESPACE=0` and `-DU_CHARSET_IS_UTF8=1`.
|
||||
|
||||
---
|
||||
|
||||
## Test UCONFIG_NO_CONVERSION
|
||||
|
||||
Make sure that the ICU4C common and i18n libraries build with
|
||||
UCONFIG_NO_CONVERSION set to 1. We cannot do this as part of "Test uconfig.h
|
||||
variations" because the test suites cannot be built like this, but the library
|
||||
code must support it.
|
||||
|
||||
The simplest is to take an ICU4C workspace, modify uconfig.h *==temporarily==*
|
||||
by changing the value of UCONFIG_NO_CONVERSION to 1, and do "make -j 6" (not
|
||||
"make check" or "make tests"). Verify that the stubdata, common & i18n libraries
|
||||
build fine; layout should build too but toolutil will fail, that's expected.
|
||||
|
||||
Fix any stubdata/common/i18n issues, revert the UCONFIG_NO_CONVERSION value, and
|
||||
verify that it still works with the normal setting.
|
||||
|
||||
If this breaks, someone probably inadvertently uses the UnicodeString(const char
|
||||
\*) constructor. See the "Check library dependencies" section and example fixes
|
||||
in [changeset 30186](http://bugs.icu-project.org/trac/changeset/30186).
|
||||
|
||||
---
|
||||
|
||||
## Test U_CHARSET_IS_UTF8
|
||||
|
||||
Verify that ICU builds with default charset hardcoded to UTF-8. To test on
|
||||
Linux,
|
||||
|
||||
```sh
|
||||
./runConfigureICU Linux CPPFLAGS="-DU_CHARSET_IS_UTF8=1"
|
||||
make -j6 check
|
||||
```
|
||||
|
||||
Any problems will show up as compilation or test errors.
|
||||
|
||||
Rather than setting the CPPFLAGS, you can also temporarily add `#define
|
||||
U_CHARSET_IS_UTF8 1` in unicode/platform.h before it gets its default
|
||||
definition, or modify the default definition there. (In ICU 4.8 and earlier,
|
||||
this flag was in unicode/utypes.h.)
|
||||
|
||||
This works best on a machine that is set to use UTF-8 as its system charset,
|
||||
which is not possible on Windows.
|
||||
|
||||
The automated build system should have a machine that sets both
|
||||
`-DU_USING_ICU_NAMESPACE=0` and `-DU_CHARSET_IS_UTF8=1`.
|
||||
|
||||
---
|
||||
|
||||
## Test U_OVERRIDE_CXX_ALLOCATION=0
|
||||
|
||||
Verify that ICU builds with U_OVERRIDE_CXX_ALLOCATION=0 on Linux. Problems will
|
||||
show as build failures.
|
||||
|
||||
```sh
|
||||
CPPFLAGS="-DU_OVERRIDE_CXX_ALLOCATION=0" ./runConfigureICU Linux
|
||||
make clean
|
||||
make -j12 check
|
||||
```
|
||||
|
||||
## ~~Test ICU_USE_THREADS=0 \[Obsolete\]~~
|
||||
|
||||
***Only necessary up to ICU4C 49.***
|
||||
|
||||
* ICU 50m1 removes ICU_USE_THREADS from the runtime code (ticket
|
||||
[ICU-9010](https://unicode-org.atlassian.net/browse/ICU-9010)).
|
||||
* It is still possible to build and test intltest with ICU_USE_THREADS=0 but
|
||||
not nearly as important.
|
||||
* In ICU 50m1, the `--disable-threads` configure option is gone. If you want
|
||||
to test with ICU_USE_THREADS=0 then temporarily change this flag in
|
||||
intltest.h or in the intltest Makefile.
|
||||
|
||||
Verify that ICU builds and tests with threading disabled. To test on Linux,
|
||||
|
||||
```sh
|
||||
./runConfigureICU Linux --disable-threads
|
||||
make check
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Test ICU4C Samples and Demos
|
||||
|
||||
To build the ICU4C samples on Windows with Visual Studio, use the following
|
||||
steps:
|
||||
|
||||
* Open the "allinone" solution file located under
|
||||
"source\\allinone\\allinone.sln".
|
||||
* Build the Debug/Release + x86/x64 configurations (all 4 configurations).
|
||||
* Make sure the generated data file (ex: "icu4c\\bin\\icudt64.dll") is not
|
||||
stub data, it should be ~26MB.
|
||||
* Open the "all" Solution file located under "source\\samples\\all\\all.sln".
|
||||
* Build both x86 and x64 using the "Batch Build" option. This is located under
|
||||
the menu Build > Batch Build.
|
||||
* Click the "Select All" button.
|
||||
* Click the "Build" button.
|
||||
* If Visual Studio returns errors using the Batch Build option, build each
|
||||
configuration individually instead.
|
||||
* The samples should all build cleanly with no errors.
|
||||
|
||||
To test the sample programs, run the "source\\samples\\all\\samplecheck.bat"
|
||||
script for each configuration, and ensure that they are successful.
|
||||
|
||||
## **Test ICU4C Demos via Docker**
|
||||
|
||||
See <https://github.com/unicode-org/icu-demos/blob/main/icu-kube/README.md>
|
||||
|
||||
---
|
||||
|
||||
## **Test ICU4J Web Demos via Docker**
|
||||
|
||||
See: <https://github.com/unicode-org/icu-demos/blob/main/icu4jweb/README.md>
|
||||
|
||||
---
|
||||
|
||||
## Test ICU4J Demos
|
||||
|
||||
These are the demo applets, see above for the icu4jweb demos.
|
||||
|
||||
To test ICU4J demo applications, cd to ICU4J directory and build and run the
|
||||
demo.
|
||||
|
||||
```sh
|
||||
$ cd icu4j
|
||||
$ ant jarDemos
|
||||
$ java -jar icu4jdemos.jar
|
||||
```
|
||||
|
||||
Above command invokes GUI demo applications. As such it has to connect to a
|
||||
X-Server. The easiest way is to run via e.g. remote desktop on the machine on
|
||||
which it is executed instead of in a ssh shell.
|
||||
|
||||
The demos include calendar, charset detection, holidays, RBNF and
|
||||
transliterator. Check if each application is working OK.
|
||||
|
||||
To check ICU4J samples, open Eclipse workspace and import icu4j-samples project
|
||||
from directory <icu4j_root>/samples. Make sure these sample code has no build
|
||||
issues. Also run sample code with main and see if each sample code runs.
|
||||
|
||||
---
|
||||
|
||||
## Test, exhaustive mode, C & J
|
||||
|
||||
For ICU4J,
|
||||
|
||||
```sh
|
||||
$ ant exhaustiveCheck
|
||||
```
|
||||
|
||||
For ICU4C, testing with an optimized build will help reduce the elapsed time
|
||||
required for the tests to complete.
|
||||
|
||||
```sh
|
||||
$ make -j6 check-exhaustive
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Test ICU4C with the Thread Sanitizer
|
||||
|
||||
The build bots run the thread sanitizer on the most interesting multithreaded
|
||||
tests. These instructions run the sanitizer on the entire test suite. The clang
|
||||
compiler is required.
|
||||
|
||||
```sh
|
||||
$ CPPFLAGS=-fsanitize=thread LDFLAGS=-fsanitize=thread ./runConfigureICU --enable-debug --disable-release Linux --disable-renaming
|
||||
$ make clean
|
||||
$ make -j6 check
|
||||
```
|
||||
14
docs/processes/release/tasks/index.md
Normal file
14
docs/processes/release/tasks/index.md
Normal file
|
|
@ -0,0 +1,14 @@
|
|||
---
|
||||
layout: default
|
||||
title: Release & Milestone Tasks
|
||||
parent: Contributors
|
||||
nav_order: 10
|
||||
has_children: true
|
||||
---
|
||||
|
||||
<!--
|
||||
© 2021 and later: Unicode, Inc. and others.
|
||||
License & terms of use: http://www.unicode.org/copyright.html
|
||||
-->
|
||||
|
||||
# Release & Milestone Tasks
|
||||
455
docs/processes/release/tasks/integration.md
Normal file
455
docs/processes/release/tasks/integration.md
Normal file
|
|
@ -0,0 +1,455 @@
|
|||
---
|
||||
layout: default
|
||||
title: Integration Tests
|
||||
parent: Release & Milestone Tasks
|
||||
grand_parent: Contributors
|
||||
nav_order: 60
|
||||
---
|
||||
|
||||
<!--
|
||||
© 2021 and later: Unicode, Inc. and others.
|
||||
License & terms of use: http://www.unicode.org/copyright.html
|
||||
-->
|
||||
|
||||
# Integration Tests
|
||||
{: .no_toc }
|
||||
|
||||
## Contents
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
1. TOC
|
||||
{:toc}
|
||||
|
||||
---
|
||||
|
||||
## Run ICU4J Locale Service Provider tests
|
||||
|
||||
JDK 6 introduced the locale service provider interface. ICU4J release include a
|
||||
special jar file (icu4j-localespi.jar) implementing the locale service provider
|
||||
interface.
|
||||
|
||||
The test case for the ICU4J locale service provider requires JRE 6 or later
|
||||
version. Otherwise, there is no extra settings except for the standard ant set
|
||||
up ( necessary. To run the test cases, use ant with the top-level build.xml with
|
||||
target "localespiCheck"
|
||||
|
||||
```sh
|
||||
$ ant localespiCheck
|
||||
```
|
||||
|
||||
You should get the output like below -
|
||||
|
||||
```
|
||||
...
|
||||
build:
|
||||
|
||||
_runLocalespiCheck:
|
||||
[java] TestAll {
|
||||
[java] BreakIteratorTest {
|
||||
[java] TestGetInstance (7.581s) Passed
|
||||
[java] TestICUEquivalent (0.832s) Passed
|
||||
[java] } (8.669s) Passed
|
||||
[java] CollatorTest {
|
||||
[java] TestGetInstance (0.900s) Passed
|
||||
[java] TestICUEquivalent (0.040s) Passed
|
||||
[java] } (0.966s) Passed
|
||||
[java] CurrencyNameTest {
|
||||
[java] TestCurrencySymbols (2.682s) Passed
|
||||
[java] } (2.683s) Passed
|
||||
[java] DateFormatSymbolsTest {
|
||||
[java] TestGetInstance (0.348s) Passed
|
||||
[java] TestICUEquivalent (0.207s) Passed
|
||||
[java] TestNynorsk (0.000s) Passed
|
||||
[java] TestSetSymbols (0.071s) Passed
|
||||
[java] } (0.631s) Passed
|
||||
[java] DateFormatTest {
|
||||
[java] TestGetInstance (0.456s) Passed
|
||||
[java] TestICUEquivalent (0.113s) Passed
|
||||
[java] TestThaiDigit (0.000s) Passed
|
||||
[java] } (0.571s) Passed
|
||||
[java] DecimalFormatSymbolsTest {
|
||||
[java] TestGetInstance (0.098s) Passed
|
||||
[java] TestICUEquivalent (0.000s) Passed
|
||||
[java] TestSetSymbols (0.000s) Passed
|
||||
[java] } (0.099s) Passed
|
||||
[java] LocaleNameTest {
|
||||
[java] TestCountryNames (2.500s) Passed
|
||||
[java] TestLanguageNames (14.262s) Passed
|
||||
[java] TestVariantNames (8.638s) Passed
|
||||
[java] } (25.402s) Passed
|
||||
[java] NumberFormatTest {
|
||||
[java] TestGetInstance (0.266s) Passed
|
||||
[java] TestICUEquivalent (0.209s) Passed
|
||||
[java] } (0.475s) Passed
|
||||
[java] TimeZoneNameTest {
|
||||
[java] TestTimeZoneNames (17.766s) Passed
|
||||
[java] } (17.766s) Passed
|
||||
[java] } (57.268s) Passed
|
||||
[java]
|
||||
[java] Test cases taking excessive time (>10s):
|
||||
[java] TestAll/LocaleNameTest/TestLanguageNames (14.262s)
|
||||
[java] TestAll/TimeZoneNameTest/TestTimeZoneNames (17.766s)
|
||||
[java]
|
||||
|
||||
BUILD SUCCESSFUL
|
||||
Total time: 1 minute 46 seconds
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Run ICU4J Test cases with JDK TimeZone
|
||||
|
||||
ICU4J provides an option to alter TimeZone implementation to use the JRE's own
|
||||
implementation. The test cases used for this is the regular ICU4J unit test
|
||||
suite, except forcing ICU4J to use JRE TimeZone by special system property -
|
||||
com.ibm.icu.util.TimeZone.DefaultTimeZoneType=JDK.
|
||||
|
||||
To run the test, you have to apply the latest time zone patch from a JRE vendor,
|
||||
because some test cases are sensitive to actual time zone transitions. For
|
||||
Oracle JRE, you should go to the J2SE download page
|
||||
<http://www.oracle.com/technetwork/java/javase/downloads/index.html> and
|
||||
download the latest JDK DST Timezone Update Tool and apply the patch to your
|
||||
local JRE.
|
||||
|
||||
To run the test case, you just need to invoke the ant target "jdktzCheck".
|
||||
|
||||
```sh
|
||||
$ ant jdktzCheck
|
||||
```
|
||||
|
||||
**Note:** You might not be able to get the update tool matching the tzdata
|
||||
version used by ICU. In this case, some test cases may reports failures.
|
||||
Unfortunately, you have to walk though the failures to see if they are expected
|
||||
or not manually in this case.
|
||||
|
||||
---
|
||||
|
||||
## Verify the Eclipse ICU4J plug-in
|
||||
|
||||
1. Make sure the Eclipse ICU4J plug-in binaries are successfully produced.
|
||||
2. Run the ICU4J plug-in test cases.
|
||||
3. Update license files, build version strings for the new release.
|
||||
|
||||
---
|
||||
|
||||
## Run Tests Without ICU Data
|
||||
|
||||
### ICU4C
|
||||
|
||||
ICU data should be removed, so that tests cannot access it. Both cintltst and
|
||||
intltest should be run with -w option and they should not crash. Every crash
|
||||
should be investigated and fixed.
|
||||
|
||||
To do this, build and test normally, then replace the ICU data shared library
|
||||
with the stubdata library and run the tests again with the -w option.
|
||||
|
||||
On Linux (adjust the version number, 60.1 in this example, as required)
|
||||
|
||||
```sh
|
||||
cd icu4c/source
|
||||
cp stubdata/libicudata.so.60.1 lib/
|
||||
cd test/intltest
|
||||
INTLTEST_OPTS=-w make check
|
||||
cd ../cintltst
|
||||
CINTLTST_OPTS=-w make check
|
||||
```
|
||||
|
||||
### ICU4J
|
||||
|
||||
ICU4J has the test target for this, but does not work as designed for now. For
|
||||
now, this task is not required for ICU4J.
|
||||
|
||||
---
|
||||
|
||||
## Verify that ICU4C tests pass without collation rule strings
|
||||
|
||||
***ICU4C 53 and later***
|
||||
|
||||
Background: [ICU-10636](https://unicode-org.atlassian.net/browse/ICU-10636)
|
||||
|
||||
### Rebuild ICU data without collation rule strings
|
||||
|
||||
#### ICU 64+
|
||||
|
||||
You need to configure ICU with a data filter config file that removes collation
|
||||
rule strings.
|
||||
|
||||
The file syntax is nicer with hjson rather than json.
|
||||
|
||||
```sh
|
||||
sudo apt install python3-pip
|
||||
pip3 install hjson
|
||||
```
|
||||
|
||||
Use an `~/icu/coll-norules.hjson` config file like this:
|
||||
|
||||
```
|
||||
{
|
||||
resourceFilters: [
|
||||
{
|
||||
categories: [
|
||||
coll_tree
|
||||
]
|
||||
rules: [
|
||||
-/UCARules
|
||||
-/collations/*/Sequence
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Configure ICU using this file:
|
||||
|
||||
```sh
|
||||
ICU_DATA_FILTER_FILE=~/icu/coll-norules.hjson ... runConfigureICU ...
|
||||
```
|
||||
|
||||
Run "make clean" (or delete just the collation .res files), then test as below.
|
||||
|
||||
#### ICU 54..63
|
||||
|
||||
This should work: `make GENRBOPTS='-k --omitCollationRules'` (-k is --strict)
|
||||
|
||||
For ICU 54..63, I went into the build output folder and did:
|
||||
|
||||
```sh
|
||||
cd data
|
||||
ICUDT=icudt63l
|
||||
rm out/build/$ICUDT/coll/*.res
|
||||
make GENRBOPTS='-k --omitCollationRules'
|
||||
```
|
||||
|
||||
If this does not work, then add this option to the configure'd data/Makefile,
|
||||
see ticket [ICU-10636](https://unicode-org.atlassian.net/browse/ICU-10636).
|
||||
|
||||
### Run the tests with data-errors-as-warnings
|
||||
|
||||
`INTLTEST_OPTS=-w CINTLTST_OPTS=-w make -j5 check`
|
||||
|
||||
See that they pass, or fix them to pass. See ticket #10636 test code changes for
|
||||
examples.
|
||||
|
||||
---
|
||||
|
||||
## Test ICU4J with only little-endian ICU4C data
|
||||
|
||||
*Only available since ICU 54.*
|
||||
|
||||
#### With ICU 64 and later:
|
||||
|
||||
* Reconfigure ICU4C with
|
||||
<code><b>ICU_DATA_BUILDTOOL_OPTS=--include_uni_core_data</b>
|
||||
./runConfigureICU Linux</code> or similar
|
||||
* Should be little-endian for coverage
|
||||
* Clean and build ICU4C: `make -j6 check`
|
||||
* Make a clean directory for testing
|
||||
* Find the .data file in the build output area, e.g.,
|
||||
`icu4c/source/data/out/tmp/icudt64l.dat`
|
||||
* Create a temporary directory such as `mkdir -p /tmp/icu4j_data_test`
|
||||
* Copy the .`dat` file to the new directory.
|
||||
* Build and test ICU4J without its own data: `ant clean && ant
|
||||
-Dicu4c.data.path=/tmp/icu4j_data_test check`
|
||||
* The configuration option sets the `ICUConfig.properties` data path
|
||||
* Verify that all tests pass.
|
||||
* If you get very many test failures, double-check that you enabled
|
||||
unicore data in the ICU4C build (see first step).
|
||||
|
||||
#### With ICU 55 through ICU 63:
|
||||
|
||||
* Rebuild ICU4C with <code>make <b>INCLUDE_UNI_CORE_DATA=1</b> check</code> or
|
||||
similar, and provide a path only for the .dat file.
|
||||
* Should be little-endian for coverage
|
||||
* Find the .data file in the build output area, e.g.,
|
||||
`data/out/tmp/icudt59l.dat`
|
||||
* Create a temporary directory such as `mkdir -p
|
||||
/tmp/icu/build/data/out/tmp`
|
||||
* Copy the .`dat` file to the new directory.
|
||||
* Build and test ICU4J without its own data: `ant clean && ant
|
||||
-Dicu4c.data.path=/tmp/icu/build/data/out/tmp check`
|
||||
* The configuration option sets the `ICUConfig.properties` data path
|
||||
* Verify that all tests pass.
|
||||
|
||||
#### ICU 54 method:
|
||||
|
||||
In `icu4j-core/src/com/ibm/icu/ICUConfig.properties` set
|
||||
`com.ibm.icu.impl.ICUBinary.dataPath` to a list of paths with all of the ICU4C
|
||||
data (should be little-endian for coverage), with a path to where the .dat file
|
||||
is and a path to the source/data/in files for data that is hardcoded in ICU4C
|
||||
and therefore not in the .dat file (e.g., uprops.icu).
|
||||
|
||||
Change `com.ibm.icu.impl.ICUData.logBinaryDataFromInputStream` to `true`, maybe
|
||||
set a breakpoint where such a message is logged.
|
||||
|
||||
Run all of the ICU4J tests, maybe in the debugger for the breakpoint, or look
|
||||
for logger output to the console.
|
||||
|
||||
Revert your config changes.
|
||||
|
||||
## Build and run testmap
|
||||
|
||||
Build and run the source/test/testmap project. (There is currently no Windows
|
||||
project defined for it.)
|
||||
|
||||
```sh
|
||||
$ cd <root of your ICU build tree>
|
||||
$ CONFIG_FILES=test/testmap/Makefile CONFIG_HEADERS= ./config.status
|
||||
$ cd test/testmap
|
||||
$ make check
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Verify XLIFF conversion
|
||||
|
||||
<span style="background-color:orange">**Note:** The following instruction does not work. Please read the comments with
|
||||
orange background. There are some issues in the current ICU XLIFF tools and the
|
||||
test case below. See the comments in
|
||||
[ticket ICU-6383](https://unicode-org.atlassian.net/browse/ICU-6383).</span>
|
||||
|
||||
Instructions for verifying the XLIFF conversion tools.
|
||||
|
||||
* Convert icu/source/test/testdata/ra.txt to XLIFF
|
||||
|
||||
`genrb -s icu/source/test/testdata -d icu/source/test/testdata/ -x -l en ra.txt`
|
||||
|
||||
<span style="background-color:orange">-d icu/source/test/testdata/ overwrite
|
||||
the existing ra.xlf. Specify another directory.</span>
|
||||
|
||||
<span style="background-color:orange">ra.txt has the top level item "ra",
|
||||
which is supposed to be the content language. Thus, with -l en, you'll get a
|
||||
warning - "The top level tag in the resource and language specified are not
|
||||
the same. Please check the input." We should use "-l ra" here.</span>
|
||||
|
||||
* Verify that the ra.xlf produced is identical to the one in CVS HEAD (except
|
||||
for generation date)
|
||||
|
||||
<span style="background-color:orange">If you use "-l ra" above, you'll get
|
||||
<file .... source-language = "ra" .... />, which is different from ra.xlf in
|
||||
the repository. Also, new line codes is broken for imported contents.</span>
|
||||
|
||||
* Convert icu/source/test/testdata/ra.xlf back to ICU format
|
||||
|
||||
`java -cp icu4j/classes com.ibm.icu.dev.tool.localeconverter.XLIFF2ICUConverter -d . -t ra ra.xlf`
|
||||
|
||||
<span style="background-color:orange">The option "-t ra" does not work,
|
||||
because ra.xlf does not contain target language data. Use "-c ra"
|
||||
instead.</span>
|
||||
|
||||
* Verify that the ra.txt produced is identical to the one in CVS HEAD (except
|
||||
for generation date)
|
||||
|
||||
<span style="background-color:orange">You cannot expect the generated ra.txt
|
||||
exactly matches the original one because of table item re-ordering, new line
|
||||
code changes, and explicit resource types (e.g. "ra {" vs. "ra:table
|
||||
{").</span>
|
||||
* Go through the steps given in
|
||||
<http://icu.sourceforge.net/docs/papers/localize_with_XLIFF_and_ICU.pdf>
|
||||
|
||||
---
|
||||
|
||||
## Test sample and demo programs
|
||||
|
||||
Build and run all of the sample and demo apps that are included with ICU, on
|
||||
each of the reference platforms. A list of them is in the
|
||||
[readme](http://icu.sanjose.ibm.com/internal/checklist/icu-progs-list.html).
|
||||
Also see the build system.
|
||||
|
||||
Another worthy test: Test suites and demos *from the previous release* should
|
||||
also compile and run with the libraries of the current release, at least when
|
||||
certain #defines are set (unless they test APIs that are deprecated and have
|
||||
been removed since)!
|
||||
|
||||
---
|
||||
|
||||
## Test data portability
|
||||
|
||||
Test if the data portability (under common endianness & charset family) is ok.
|
||||
On the ICU build server, you would use the "Build from source .dat archive"
|
||||
option. When it's not available, you would do the following:
|
||||
|
||||
1. Build ICU4C on Win32.
|
||||
2. Copy the icu/source/data/out/icudt<data_version>l.dat file into
|
||||
icu/source/data/in
|
||||
3. Delete non-essential directories from icu/source/data.
|
||||
4. Package up a clean copy of ICU for a non-Windows machine, like Linux on x86.
|
||||
5. Build ICU on the non-Windows machine from the newly created package.
|
||||
6. Run all tests on that non-Windows machine.
|
||||
|
||||
---
|
||||
|
||||
## Run the environment tests
|
||||
|
||||
Run
|
||||
[environmentTest.sh](https://github.com/unicode-org/icu/blob/main/tools/release/c/environmentTest.sh)
|
||||
on a Linux machine which has many (all possible?) POSIX locales installed. This
|
||||
test verifies that the ICU test suite will work regardless of a user's default
|
||||
locale and timezone. This test should be run on a fast machine with several CPU
|
||||
cores. This will take a long time to run. Here are the steps to run the test.
|
||||
|
||||
1. cd icu4c/source/
|
||||
2. ./runConfigureICU Linux
|
||||
3. make check
|
||||
4. cd ../../tools/release/c/
|
||||
5. ./environmentTest.sh
|
||||
6. Wait a while for the tests to finish. The logs will be written in each test
|
||||
directory. e.g. icu4c/source/test/intltest/intltest-\*.txt. A message will
|
||||
be printed from each spawned test script when it finishes.
|
||||
7. grep the logs for any test failures when the tests are done.
|
||||
|
||||
---
|
||||
|
||||
## Run Thread Sanitizer tests
|
||||
|
||||
Thread sanitizer testing is one of the standard Travis builds. If it is passing
|
||||
there, nothing further is required.
|
||||
|
||||
To run manually, on a Linux system with clang,
|
||||
|
||||
```sh
|
||||
cd icu4c/source
|
||||
CPPFLAGS=-fsanitize=thread LDFLAGS=-fsanitize=thread ./runConfigureICU --enable-debug --disable-release Linux
|
||||
make clean
|
||||
make -j6 check
|
||||
```
|
||||
|
||||
Errors are displayed at the point they occur, and stop further testing.
|
||||
|
||||
---
|
||||
|
||||
## Run Address Sanitizer tests
|
||||
|
||||
Address sanitizer testing is included in the standard Linux with Clang Travis
|
||||
builds. If it is passing there, nothing further is required.
|
||||
|
||||
To run manually, on a Linux system with clang,
|
||||
|
||||
```sh
|
||||
cd icu4c/source
|
||||
CPPFLAGS=-fsanitize=address LDFLAGS=-fsanitize=address ./runConfigureICU --enable-debug --disable-release Linux
|
||||
make clean
|
||||
make -j6 check
|
||||
```
|
||||
|
||||
Memory leaks are summarized at the end. Other errors are displayed at the point
|
||||
they occur, and stop further testing.
|
||||
|
||||
---
|
||||
|
||||
## ICU4J Serialization Compatibility Test Data
|
||||
|
||||
The regular ICU4J unit test includes serialization compatibility tests. The test
|
||||
case creates an ICU service object from serialized data created by a former
|
||||
version of ICU. When we prepare a new release, the serialization compatibility
|
||||
test data should be created and checked in for future testing. This task is
|
||||
usually done just before publishing release candidate.
|
||||
|
||||
1. Run regular ICU4J unit tests - `ant check`
|
||||
2. Make sure the unit tests pass successfully.
|
||||
3. Run - `ant serialTestData`
|
||||
4. Copy a folder with ICU version (e.g. ICU_61.1) generated under <icu4j
|
||||
root>/out/serialTestData to <icu4j
|
||||
root>/main/tests/core/src/com/ibm/icu/dev/test/serializable/data.
|
||||
5. You may delete older serialization test data from the directory (but keep
|
||||
the oldest one - ICU_3.6).
|
||||
6. Run `ant check` again before committing the changes.
|
||||
131
docs/processes/release/tasks/legal/find_textfiles
Normal file
131
docs/processes/release/tasks/legal/find_textfiles
Normal file
|
|
@ -0,0 +1,131 @@
|
|||
#!/usr/bin/perl -w
|
||||
#
|
||||
# Copyright (C) 2012, 2017: Unicode, Inc. and others.
|
||||
# License & terms of use: http://www.unicode.org/copyright.html
|
||||
#
|
||||
#####################################################################
|
||||
# Name : find_textfiles #
|
||||
# Full path : /home/umesh/bin/find_textfiles #
|
||||
# Type : Perl Script. Needs Perl 5. #
|
||||
# Description : Finds the text files under a directory #
|
||||
# Prunes CVS directories if -nocvs is provided #
|
||||
# Prunes RCS directories if -norcs is provided #
|
||||
# Prunes SCCS directories if -nosccs is provided #
|
||||
# Author : Umesh Nair (umesh@google.com) #
|
||||
# #
|
||||
#-------------------------------------------------------------------#
|
||||
# Maintenance Block: #
|
||||
# Date Changed by Description #
|
||||
# ---- ---------- ----------- #
|
||||
# May 2000 Umesh Nair Initial version of the script #
|
||||
# Mar 2002 Umesh Nair Added -h option #
|
||||
# May 2008 Umesh Nair Added -nosvn and -novc #
|
||||
# #
|
||||
#####################################################################
|
||||
|
||||
use strict;
|
||||
use File::Find;
|
||||
|
||||
my ($skipCvs, $skipRcs, $skipSccs, $skipSvn, $skipVc, $skipEclipse) = (0, 0, 0, 0, 0);
|
||||
my $help = 0;
|
||||
|
||||
while ((defined $ARGV[0]) and ($ARGV[0] =~ /\A\-/)) {
|
||||
my $option = shift;
|
||||
chomp $option;
|
||||
($skipCvs = 1) if ($option =~ /nocvs/);
|
||||
($skipSccs = 1) if ($option =~ /nosccs/);
|
||||
($skipSvn = 1) if ($option =~ /nosvn/);
|
||||
($skipVc = 1) if ($option =~ /novc/);
|
||||
($skipEclipse = 1) if ($option =~ /noeclipse/);
|
||||
($help = 1) if ($option =~ /h/);
|
||||
}
|
||||
|
||||
if ($help) {
|
||||
exec "pod2man $0 | nroff -man |". ($ENV{"PAGER"} || 'more -s');
|
||||
}
|
||||
|
||||
if (@ARGV == 0) {
|
||||
find (\&wanted, '.');
|
||||
} else {
|
||||
find (\&wanted, @ARGV);
|
||||
}
|
||||
|
||||
sub wanted {
|
||||
unless (($skipVc and (/\.vcproj$/ or /\.vcxproj$/ or /\.sln$/ or /\.dsp$/ or /\.dsw$/ or /\.filters$/))
|
||||
or ($skipEclipse and (/\.project$/ or /\.classpath$/ or /\.prefs$/ or /\.launch$/))) {
|
||||
print "$File::Find::name\n" if (-f and -T );
|
||||
}
|
||||
($File::Find::prune = 1)
|
||||
if (
|
||||
($skipCvs and /^CVS$/) or
|
||||
($skipRcs and /^RCS$/) or
|
||||
($skipSccs and /^SCCS$/) or
|
||||
($skipSvn and /^\.svn$/)
|
||||
);
|
||||
}
|
||||
|
||||
__END__
|
||||
|
||||
=head1 NAME
|
||||
|
||||
find_textfiles - Finds the text files under a directory
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
find_textfiles [C<-nocvs>] [C<-norcs>] [C<-nosccs>] [C<-nosvn>] [C<-novc>] [C<-noeclipse>] [ dir1 [ dir2 ] .... ]
|
||||
|
||||
find_textfiles [C<-h>]
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
This script recursively searches the specified directories (current
|
||||
directory if no parameter is passed) for text files, and lists the
|
||||
filenames on the standard output, one file per line.
|
||||
|
||||
The directories named 'CVS', 'RCS' and 'SCCS' may be skipped by
|
||||
specifying the switches -nocvs, -norcs and -nosccs respectively.
|
||||
|
||||
=head1 OPTIONS
|
||||
|
||||
=over 4
|
||||
|
||||
=item C<-h>
|
||||
|
||||
Displays this help document.
|
||||
|
||||
=item C<-nocvs>
|
||||
|
||||
Prunes all directories named 'CVS' and everything under that.
|
||||
|
||||
=item C<-norcs>
|
||||
|
||||
Prunes all directories named 'RCS' and everything under that.
|
||||
|
||||
=item C<-nosccs>
|
||||
|
||||
Prunes all directories named 'SCCS' and everything under that.
|
||||
|
||||
=item C<-nosvn>
|
||||
|
||||
Prunes all directories named '.svn' and everything under that.
|
||||
|
||||
=item C<-novc>
|
||||
|
||||
Excludes all VC++ files, i.e., *.vcproj, *vcxproj, *.dsw, *.dsp, *.filters.
|
||||
|
||||
=item C<-noeclipse>
|
||||
|
||||
Excludes all Eclipse files, i.e., .project, .classpath, *.prefs, *.launch.
|
||||
|
||||
=back
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
find_binaries
|
||||
|
||||
=head1 AUTHOR
|
||||
|
||||
Umesh Nair, 2000.
|
||||
|
||||
=cut
|
||||
|
||||
54
docs/processes/release/tasks/legal/index.md
Normal file
54
docs/processes/release/tasks/legal/index.md
Normal file
|
|
@ -0,0 +1,54 @@
|
|||
---
|
||||
layout: default
|
||||
title: Legalities
|
||||
parent: Release & Milestone Tasks
|
||||
grand_parent: Contributors
|
||||
nav_order: 70
|
||||
---
|
||||
|
||||
<!--
|
||||
© 2021 and later: Unicode, Inc. and others.
|
||||
License & terms of use: http://www.unicode.org/copyright.html
|
||||
-->
|
||||
|
||||
# Legalities
|
||||
|
||||
## 1. Scan for Copyright notices
|
||||
|
||||
Check source and data files, especially newly contributed ones, to make sure the
|
||||
proper copyright notice is in place. For example,
|
||||
|
||||
```
|
||||
© 2016 and later: Unicode, Inc. and others.
|
||||
License & terms of use: http://www.unicode.org/copyright.html#License
|
||||
```
|
||||
|
||||
Scan the source code to make sure that every file that was touched recently has
|
||||
the current year in the copyright statement. See the [ICU Copyright
|
||||
Scanner](../../../copyright-scan.md) page and follow the link to the scripts and
|
||||
the readme.
|
||||
|
||||
Scan the source code to include third-party company names in copyright notices
|
||||
if necessary.
|
||||
|
||||
~~Scan for text files that do not contain the word "Copyright": find_textfiles
|
||||
-nosvn -novc -noeclipse | xargs grep -i -L Copyright (See the find_textfiles
|
||||
Perl script attached to this page.) There are files without word "Copyright" in
|
||||
ICU source repository including some test data files (no comment syntax defined
|
||||
for these test data files), Unicode data files, tzcode source files and others.
|
||||
Review the output file list and determine if each of them should have ICU
|
||||
copyright statement or not.~~ ***The script [find_textfiles](find_textfiles)
|
||||
associated with this document is not maintained. Use the ICU Copyright Scanner
|
||||
above instead.***
|
||||
|
||||
## 2. Update license files
|
||||
|
||||
Check ICU, Unicode and other license terms. Make sure these files are up to
|
||||
date. The [Unicode data and software license
|
||||
term](http://www.unicode.org/copyright.html) is updated annually (usually year
|
||||
number only). The easiest way to get the updated license is to do View Source on
|
||||
unicode.org/copyright.html and scroll down to the plaintext version of the
|
||||
software license ("Exhibit A").
|
||||
|
||||
See [svn changeset r39632](https://github.com/unicode-org/icu/commit/0001f6c5e92f6f3a8d66c7dbc47cc24df7633a71)
|
||||
for an example; there should be only two files to update.
|
||||
111
docs/processes/release/tasks/miscellaneous.md
Normal file
111
docs/processes/release/tasks/miscellaneous.md
Normal file
|
|
@ -0,0 +1,111 @@
|
|||
---
|
||||
layout: default
|
||||
title: Miscellaneous
|
||||
parent: Release & Milestone Tasks
|
||||
grand_parent: Contributors
|
||||
nav_order: 80
|
||||
---
|
||||
|
||||
<!--
|
||||
© 2021 and later: Unicode, Inc. and others.
|
||||
License & terms of use: http://www.unicode.org/copyright.html
|
||||
-->
|
||||
|
||||
# Miscellaneous
|
||||
{: .no_toc }
|
||||
|
||||
## Contents
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
1. TOC
|
||||
{:toc}
|
||||
|
||||
---
|
||||
|
||||
## Complete code reviews
|
||||
|
||||
Nag all the reviewers to finish reviewing the code and change the status of
|
||||
bugs.
|
||||
|
||||
---
|
||||
|
||||
## Check in serialization compatibility test data
|
||||
|
||||
ICU4J unit test contains serialization compatibility test cases. When a new
|
||||
reference version is released, we build serialized object data with the version
|
||||
and use it for future testing.
|
||||
|
||||
1. Run "ant serialTestData" at ICU4J root directory
|
||||
2. The target generates test data and runs some serialization test cases.
|
||||
3. Once you confirm the test runs clean, copy
|
||||
`out/serialTestData/ICU_<version>` to
|
||||
`main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_<version>`.
|
||||
|
||||
---
|
||||
|
||||
## Release ticket
|
||||
|
||||
After every milestone (GA / RC / Milestone-N) is completed, create a new release
|
||||
ticket in ICU Jira, then add the ticket link to the next
|
||||
[milestone](http://bugs.icu-project.org/trac/roadmap). The release ticket is
|
||||
used for BRS tasks, such as version update, tagging new version, merging post RC
|
||||
fixes from trunk and others.
|
||||
|
||||
---
|
||||
|
||||
## Check integrity of Jira issues in commit messages
|
||||
|
||||
Every commit being shipped in the next ICU release should be labeled with a Jira
|
||||
ticket that is marked as fixed with the correct fix version. Further, there
|
||||
should be no Jira tickets marked as fixed with the current fixVersion that do
|
||||
not have commits. To check this, run the following tool:
|
||||
|
||||
<https://github.com/unicode-org/icu/tree/main/tools/commit-checker>
|
||||
|
||||
Follow the instructions in the README file to generate the report and send it
|
||||
for review.
|
||||
|
||||
---
|
||||
|
||||
## Fix Mis-ticketted commits
|
||||
|
||||
If the commit checker tool above reports any malformed commit messages, it might
|
||||
mean that a bad commit made its way onto ICU main branch. To fix this, a rebase
|
||||
is required. Since rebases can be disruptive, confirm with ICU-TC before
|
||||
performing one. If ICU-TC agrees to perform a rebase, initiate the process as
|
||||
follows:
|
||||
|
||||
$ git checkout main; git pull --ff-only upstream main
|
||||
|
||||
$ git rebase -i --preserve-merges latest
|
||||
|
||||
Note: although tempting, please do not use --committer-date-is--author-date. It
|
||||
changes the order of commits in ways we don't want to do.
|
||||
|
||||
In the interactive rebase window, choose commit messages to rewrite using the
|
||||
"reword" option. Save and exit the interactive screen, and then edit each commit
|
||||
message.
|
||||
|
||||
When ready, force-push the main branch to your fork and give ICU-TC a day or two
|
||||
to review. Before force-pushing to upstream, create a new branch on upstream
|
||||
with the latest commit on the old main branch; name it something like
|
||||
"pre63-old-main". When ready, disable branch protection on main, force-push,
|
||||
and then reapply branch protection. Create a new branch named something like
|
||||
"pre63-new-main" to allow users to easily switch between the two heads.
|
||||
|
||||
Send an email to icu-support explaining the change and how to deal with it. You
|
||||
can use [this email](https://sourceforge.net/p/icu/mailman/message/36426642/) as
|
||||
a model.
|
||||
|
||||
---
|
||||
|
||||
## Scrub closed issues in code
|
||||
|
||||
(1) Search for "TODO(12345)" to detect TODO items for closed issues.
|
||||
|
||||
(2) Do the same for logKnownIssue. (the data related logKnownIssues are often
|
||||
addressed during CLDR data integration)
|
||||
|
||||
If the TODO or logKnownIssue references a closed issue, if the problem is fixed,
|
||||
remove the TODO/logKnownIssue, or if the problem is not fixed, open a new issue
|
||||
and update the reference in the code.
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 6.8 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 6 KiB |
BIN
docs/processes/release/tasks/publish/azure-ci-builds.png
Normal file
BIN
docs/processes/release/tasks/publish/azure-ci-builds.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 12 KiB |
517
docs/processes/release/tasks/publish/index.md
Normal file
517
docs/processes/release/tasks/publish/index.md
Normal file
|
|
@ -0,0 +1,517 @@
|
|||
---
|
||||
layout: default
|
||||
title: Publish
|
||||
parent: Release & Milestone Tasks
|
||||
grand_parent: Contributors
|
||||
nav_order: 90
|
||||
---
|
||||
|
||||
<!--
|
||||
© 2021 and later: Unicode, Inc. and others.
|
||||
License & terms of use: http://www.unicode.org/copyright.html
|
||||
-->
|
||||
|
||||
# Publish
|
||||
{: .no_toc }
|
||||
|
||||
## Contents
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
1. TOC
|
||||
{:toc}
|
||||
|
||||
---
|
||||
|
||||
## Create a release branch in GitHub
|
||||
|
||||
Once the branch is created, only changes necessary for the target release are
|
||||
merged in from the trunk.
|
||||
|
||||
---
|
||||
|
||||
## Upgrade LocaleExplorer and other demos/samples
|
||||
|
||||
... to the ICU project site.
|
||||
|
||||
Build the icuapps module following the README's. Update code and/or docs as
|
||||
needed. "Reference" platforms for icuapps are: RedHat Linux and win32. On Linux,
|
||||
icuapps is built against the "make install "'ed ICU. So, run ICU4C's configure
|
||||
with --prefix=/some/where pointing to where ICU4C should be installed, and also
|
||||
follow icuapps's README.
|
||||
|
||||
Install the new locale explorer and other demos/samples onto the public demo
|
||||
hosting site.
|
||||
|
||||
---
|
||||
|
||||
## ICU Collation Demo
|
||||
|
||||
Update the ICU collation demo's `index.html` with the new ICU version’s
|
||||
available collators.
|
||||
|
||||
1. Do a clean build (configure, make clean, make install, make check).
|
||||
1. Otherwise, the data build may not pick up a new locale into the
|
||||
coll/res_index.txt file.
|
||||
2. Run [icu-demos >
|
||||
webdemo/collation/build.sh](https://github.com/unicode-org/icu-demos/blob/main/webdemo/collation/build.sh)
|
||||
(after modifying it for your system).
|
||||
3. Copy-paste the output `available-collators.txt` into `index.html`.
|
||||
1. Or, easier: Use a GUI difftool (e.g., meld) to compare the two and move
|
||||
the changes into index.html.
|
||||
2. `meld webdemo/collation/index.html ../available-collators.txt`
|
||||
4. See for example the changes for
|
||||
[ICU-11355](https://unicode-org.atlassian.net/browse/ICU-11355)
|
||||
|
||||
For details see the comments at the start of the build.sh file.
|
||||
|
||||
---
|
||||
|
||||
## Repository Branch and Tags
|
||||
|
||||
⚠ Careful! The following examples contain specific version, revision and ticket
|
||||
numbers. Adjust them for the current release! Easiest: Paste into an editor,
|
||||
fix, then paste into the terminal.
|
||||
|
||||
### Creating Maintenance Branch.
|
||||
|
||||
Sanity check: Update to the latest repository revision. (Main branch if you
|
||||
copy from main, maintenance branch if you copy from there.)
|
||||
|
||||
```sh
|
||||
git checkout main
|
||||
git pull upstream main
|
||||
git log -n1
|
||||
commit bcd0... (HEAD -> main, upstream/main, ...)
|
||||
```
|
||||
|
||||
Ensure that your local branch is in sync with the upstream branch. Make sure you
|
||||
are checking the upstream remote, and not your fork!
|
||||
|
||||
Build & test ICU4C & ICU4J on your machine.
|
||||
|
||||
Create the maintenance branch from the current known good main ref.
|
||||
|
||||
```sh
|
||||
git checkout -b maint/maint-63
|
||||
git push -u upstream maint/maint-63
|
||||
```
|
||||
|
||||
#### Tagging
|
||||
|
||||
Use the GitHub GUI to create both the "release" and the "tag" at the same time:
|
||||
|
||||
<https://github.com/unicode-org/icu/releases/new>
|
||||
|
||||
Fill in the tag name, such as "release-63-rc" or "release-63-1", and make the
|
||||
target the "maint/maint-xx" branch (such as maint/maint-63).
|
||||
|
||||
Set the title to "ICU 63 RC" or "ICU 63.1". Fill in the description using the
|
||||
text from the announcement email. (You can also look at previous releases and
|
||||
possibly re-use some of the generic text, such as links to the API docs, etc.)
|
||||
|
||||
Your screen should look like this:
|
||||
|
||||
|
||||
|
||||
For the release candidate tag, please check the box that says "Pre-Release".
|
||||
|
||||
We no longer need to add the note about Git LFS files, as GitHub now includes
|
||||
them in the auto-generated .zip downloads.
|
||||
|
||||
Click the "Publish Release" button to make the tag.
|
||||
|
||||
Note: The "latest" tag is no longer updated. It was agreed by the ICU-TC to be
|
||||
deleted around the 64.2 time-frame, as it doesn't work well with with Git. (You
|
||||
need to force-push the new tag, and if somebody has already cloned the
|
||||
repository, they might have something different for the "latest" tag).
|
||||
A possible future alternative might be a sym-link folder, or HTTP redirect that
|
||||
points to the latest release.
|
||||
|
||||
#### Maintenance release
|
||||
|
||||
Create the maintenance release tag from the maintenance branch, as above.
|
||||
|
||||
Update the "latest" tag.
|
||||
|
||||
### ~~ICU 58 and earlier~~
|
||||
|
||||
~~Tag related svn files, for **icu**, **icu4j** and (for final releases)
|
||||
**tools** file trees. We tag the tools tree so that we can reproduce the Unicode
|
||||
tools that were used for the Unicode data files in this release.~~
|
||||
|
||||
~~For a Release Candidate, just tag, don't branch, and only tag icu & icu4j.~~
|
||||
|
||||
~~For the final release, branch then tag. Copy the trunk to maint/maint-4-8 and
|
||||
copy that to tags/release-4-8. Specify the source revision explicitly via -r so
|
||||
that you don't inadvertently pick up an unexpected changeset. Make sure that the
|
||||
trunk at the source revision is good.~~
|
||||
|
||||
~~We do not tag the data & icuapps trees. Steven Loomis writes on 2011-may-23:~~
|
||||
|
||||
> ~~My thought had been (in the CVS days) to take a 'snapshot' of these items.
|
||||
> However, in SVN all you need is a date or a revision number (such as
|
||||
> r30140).~~
|
||||
|
||||
> ~~So, probably, we don't need to tag these two (icuapps or data).~~
|
||||
|
||||
> ~~Tools are more important because those tools are actually used in the
|
||||
> release.~~
|
||||
|
||||
### Create ICU download page
|
||||
|
||||
Create the download page before the first milestone, if we have one, or before
|
||||
the release candidate.
|
||||
|
||||
Log into the ICU homepage Google Site. (If you don't have write access, ask one
|
||||
of the editors to grant you access.)
|
||||
|
||||
Verify that there is not already a page for the upcoming release: Either via the
|
||||
sitemap, or on the bottom of the main download page where it says something like
|
||||
"Subpages (27): View All".
|
||||
|
||||
Copy the download page for the last release: Go to that page, gear menu, Copy
|
||||
page; "Name your page" using just the major version number for now (e.g., "61")
|
||||
so that the page URL is just that number, select "Put page under Downloading
|
||||
ICU", click the red COPY button.
|
||||
|
||||
Adjust the new page as needed: Change the title to "Download ICU 61 Release
|
||||
Candidate" (with the right version number...), remove contents specific to the
|
||||
previous release, update all version numbers, update all links.
|
||||
|
||||
Put a big, bold+italics, red warning at the top like "This version has not been
|
||||
released yet. Use it for testing but not in production!"
|
||||
|
||||
Save the page. It is generally a good idea to save frequently. For further
|
||||
edits, simply go back into edit mode. (Keyboard shortcut 'e' for edit, ctrl+s
|
||||
for save.)
|
||||
|
||||
Add new contents for the upcoming release: Grab some text from the sibling
|
||||
Unicode and CLDR release notes, look at the proposal status doc for this
|
||||
release, make a pass through the api/enhancement tickets fixed in this release
|
||||
or under reviewing/reviewfeedback.
|
||||
|
||||
Look at the download pages of the last two releases for templates for things
|
||||
like a Migration Issues section etc.
|
||||
|
||||
Ask everyone on the team to add stuff & details.
|
||||
|
||||
**Once the page has been created and various people are invited to edit it,
|
||||
everyone should keep editing short so that the page is not locked for others for
|
||||
long periods of time.**
|
||||
|
||||
### Maintenance release
|
||||
|
||||
For a maintenance release, look at the ICU 60 page which includes 60.2.
|
||||
|
||||
---
|
||||
|
||||
## Milestone on the main download page
|
||||
|
||||
We had the following HTML on the main download page for ICU 4.8M1 = 4.7.1:
|
||||
|
||||
```html
|
||||
<h3 style="background-color:rgb(102, 102, 102);color:white;margin-bottom:0pt;margin-top:12pt;padding-left:0.75em;font-size:1em;font-family:Arial,Helvetica,sans-serif">Development Milestones</h3>
|
||||
<table border="0"><p style="font-size:10pt;font-family:Arial,Helvetica,sans-serif">Development milestone versions of ICU can be downloaded below. A development milestone is a stable snapshot build for next ICU major version. These binaries and source code are provided for evaluation purpose and should be not be used in production environments. New APIs or features in a milestone release might be changed or removed without notice. </p>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td style="width:105px;height:16px"> <b>Release</b></td>
|
||||
<td style="width:792px;height:16px"> <b>Major Changes<br>
|
||||
</b></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td style="width:105px;height:29px"> <a href="https://sites.google.com/site/icusite/download/471">4.8M1 (4.7.1)</a><br>
|
||||
</td>
|
||||
<td style="width:792px;height:29px"> CLDR 1.9.1+, Parent locale override, Dictionary type trie, Alphabetic index (C), Compound text encoding (C), JDK7 Locale conversion (J)<br>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</span><br>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Upload Release Source / Binaries
|
||||
|
||||
Download Directories are located at, for example,
|
||||
`icu-project.org:/home/htdocs/ex/files/icu4c/4.4.2`
|
||||
corresponding to <http://download.icu-project.org/ex/files/icu4c/4.4.2/>
|
||||
Look at previous releases for an example.
|
||||
|
||||
### Java Source/Bin:
|
||||
|
||||
Follow instructions here: [Building ICU4J Release Files](../release-build.md)
|
||||
|
||||
### C source/binary:
|
||||
|
||||
<span style="background:yellow">***WORK IN PROGRESS***</a>
|
||||
|
||||
#### Source and Linux Binaries:
|
||||
|
||||
Important: this step works with Unix make + docker.
|
||||
|
||||
First, install *docker* and *docker-compose. D*o not proceed until *docker run
|
||||
hello-world* works!
|
||||
|
||||
```sh
|
||||
$ git clone https://github.com/unicode-org/icu-docker.git
|
||||
$ cd icu-docker/src
|
||||
$ git clone --branch release-64-rc --depth 1 https://github.com/unicode-org/icu.git
|
||||
$ cd icu
|
||||
$ git lfs fetch
|
||||
$ git lfs checkout
|
||||
$ cd ../..
|
||||
$ less [README.md](https://github.com/unicode-org/icu-docker/blob/main/README.md) # Follow these instructions.
|
||||
```
|
||||
|
||||
* Source and binaries are created in ./dist/.
|
||||
* The names [don't match what's needed on
|
||||
output](https://github.com/unicode-org/icu-docker/issues/1) so be sure to
|
||||
rename.
|
||||
|
||||
**Note:** If you only want to make a source tarball (.tgz/.zip), then you can
|
||||
run \`make dist\`.
|
||||
|
||||
* This will produce a source tarball and will include a pre-compiled .dat file
|
||||
under icu4c/source/data/in/.
|
||||
* Note: This tarball will also omit all of the data sub-directories containing
|
||||
locale data.
|
||||
* Note that the source is taken from the git repository itself, and not your
|
||||
local checkout. (Thus it will exclude any local uncommitted changes).
|
||||
|
||||
#### Windows Binary:
|
||||
|
||||
* Manual process:
|
||||
* Build with MSVC x64 Release. (See the ICU
|
||||
[readme.html](https://github.com/unicode-org/icu/blob/main/icu4c/readme.html)
|
||||
file for details).
|
||||
* Open a command prompt.
|
||||
```
|
||||
cd C:\icu\icu4c\ (or wherever you have ICU located).
|
||||
powershell
|
||||
Set-ExecutionPolicy -Scope Process Unrestricted
|
||||
.\packaging\distrelease.ps1 -arch x64
|
||||
```
|
||||
This will produce the file "source\dist\icu-windows.zip", which will
|
||||
need to be renamed before uploading.
|
||||
* For example, the binaries for ICU4C v61.1 generated with VS2017 were
|
||||
named "icu4c-61_1-Win64-MSVC2017.zip".
|
||||
* Note: As of ICU 68, the pre-built binaries use MSVC2019 instead of
|
||||
MSVC2017.
|
||||
* Using the output from the build bots:
|
||||
* Navigate to the GitHub page for the commits on the
|
||||
`maint/maint-<version>` branch.
|
||||
* Ex: https://github.com/unicode-org/icu/commits/maint/maint-64
|
||||
* Click on the green check mark (✔) on the most recent/last commit. (It
|
||||
might be a red X if the builds failed, hopefully not).
|
||||
* This will open up a pop-up with links to various CI builds.
|
||||
* Click on one of the various links that says "Details" for the Azure CI
|
||||
builds.
|
||||
* This will open up the GitHub overview of the build status.<br>
|
||||
<br>
|
||||
* Click on the link "View more details on Azure Pipelines" link.
|
||||
* This will take you to the actual Azure CI build page.
|
||||
* On the top right of the page there should be a button titled
|
||||
"Artifacts". Click this and it should show a drop-down with various ZIP
|
||||
files that you can download.<br>
|
||||
<br>
|
||||
* The ZIP may automatically download for you.
|
||||
* However, if you are signed-in to visualstudio.com then you might see a
|
||||
dialog titled "Artifacts explorer".
|
||||
* In this case click on the name, then the "..." button to download the
|
||||
zip file.<br>
|
||||
<br>
|
||||
* Download both the x64 (64-bit) and x86 (32-bit) ZIP files.
|
||||
* For each architecture:
|
||||
* Extract the Zip file. (It will have a name like
|
||||
"20190829.6_ICU4C_MSVC_x64_Release.zip").
|
||||
* Navigate into the folder with the same name.
|
||||
* Rename the file "icu-windows.zip" to the appropriate name:
|
||||
* Ex: The x64 zip for version 64.1 was named
|
||||
"icu4c-64_1-Win64-MSVC2017.zip"
|
||||
* Ex: The x86 zip for version 64.1 was named
|
||||
"icu4c-64_1-Win32-MSVC2017.zip"
|
||||
* Note: Note: As of ICU 68, the pre-built binaries use MSVC2019
|
||||
instead of MSVC2017.
|
||||
* Note: For RC releases the name looked like this:
|
||||
"icu4c-64rc-Win64-MSVC2017.zip"
|
||||
* ~~AIX Bin:~~ (AIX is broken and ignored for now.)
|
||||
* ~~login to gcc119.fsffrance.org and copy the ICU4C source archive
|
||||
created above to there.~~
|
||||
* ~~$ gzip -dc icu4c-XXX-src.tgz | tar xf -~~
|
||||
* ~~$ cd icu~~
|
||||
* ~~$ PATH=/opt/IBM/xlC/13.1.3/bin:$PATH source/runConfigureICU AIX~~
|
||||
* ~~(The above command line doesn't actually work, see [ICU Ticket
|
||||
ICU-13639](https://unicode-org.atlassian.net/browse/ICU-13639) for a
|
||||
workaround.)~~
|
||||
* ~~$ gmake DESTDIR=/tmp/icu releaseDist~~
|
||||
* ~~That last step will create a directory in **/tmp/icu** - zip that up
|
||||
to make the release.~~
|
||||
* ~~In case /tmp happens to be full, see the [mailing list
|
||||
archive](https://sourceforge.net/p/icu/mailman/message/36275940/) for
|
||||
advice.~~
|
||||
|
||||
### Signing archives and creating checksums:
|
||||
|
||||
#### Step 1. PGP files:
|
||||
|
||||
Sign all archives created above with your own personal PGP key. This creates a
|
||||
file with .asc as the suffix.
|
||||
|
||||
```sh
|
||||
$ gpg --armor --detach-sign icu4c-xxx-xxx.zip
|
||||
# To verify
|
||||
$ gpg --verify icu4c-xxx-xxx.zip.asc
|
||||
```
|
||||
|
||||
#### Step 2. MD5 files:
|
||||
|
||||
Use md5sum or [cfv](http://cfv.sf.net) to create [md5](https://en.wikipedia.org/wiki/MD5) hash sums for three groups of files:
|
||||
|
||||
* icu4j (all files),
|
||||
* icu4c (source),
|
||||
* icu4c (binaries).
|
||||
|
||||
Using md5sum to create and verify the checksum files:
|
||||
|
||||
<pre><code><b><b>md5sum source1 source2 ... sourceN > icu4c_sources.md5</b></b> # To verifymd5sum -c icu4c_sources.md5
|
||||
</code></pre>
|
||||
|
||||
Alternatively, use cfv to create and verify md5 files:
|
||||
|
||||
```sh
|
||||
cfv -t md5 -C -f icu-……-src.md5 somefile.zip somefile.tgz …
|
||||
# To verify
|
||||
cfv -f icu-……-src.md5
|
||||
```
|
||||
|
||||
#### Step 3. SHASUM512.txt
|
||||
|
||||
Create an additional hash sum file SHASUM512.txt file with:
|
||||
|
||||
```sh
|
||||
shasum -a 512 *.zip *.tgz | tee SHASUM512.txt
|
||||
```
|
||||
|
||||
This file should also be GPG signed. Check the .asc with \`gpg verify\`.
|
||||
|
||||
### Update the Download Page Gadgets
|
||||
|
||||
Update the gadgets on the download page to point at the new URL for the
|
||||
binaries.
|
||||
|
||||
1. Edit the download page.
|
||||
2. Click on the Gadget area.
|
||||
3. Click on the "gear" icon.
|
||||
4. Update the URL field with the new URL.
|
||||
1. For example: The ICU4C 63.1 Binaries URL was:
|
||||
<http://apps.icu-project.org/icu-jsp/downloadSection.jsp?ver=63.1&base=c&svn=release-63-1>
|
||||
|
||||
#### Check the ICU public site for the new release
|
||||
|
||||
Make sure that, aside from download pages, homepages, news items, feature lists
|
||||
and feature comparisons, etc. are updated. Upload the new API references. Update
|
||||
the User Guide.
|
||||
|
||||
#### Update the Trac release number list for ICU4C and ICU4J. <<?? STILL VALID ??>>
|
||||
|
||||
Update the ICU release number list by going to "Admin>Versions" in Trac, and add
|
||||
the new ICU version.
|
||||
|
||||
#### Post-release cleanup
|
||||
|
||||
* Cleanup the milestone in the ICU Trac. Move left over items to future
|
||||
milestones. Close the milestone.
|
||||
* Look for TODO comments in the source code and file new tickets as required.
|
||||
* Delete and retag
|
||||
[latest](http://source.icu-project.org/repos/icu/tags/latest/) (**ONLY**
|
||||
after GA release, including maintenance!) << IS THIS STILL VALID WITH GIT?
|
||||
>>
|
||||
|
||||
---
|
||||
|
||||
## Update online demos
|
||||
|
||||
Update online demos/tools to the latest version:
|
||||
|
||||
* ICU demos (eg <http://demo.icu-project.org/icu-bin/idnbrowser>)
|
||||
* CLDR Survey tool (eg <http://unicode.org/cldr/apps/about.jsp>)
|
||||
* Unicode Utilities (eg <http://unicode.org/cldr/utility/character.jsp>)
|
||||
|
||||
### Online information update
|
||||
|
||||
Collation and [comparison](../../../../charts/comparison/index.md) charts need
|
||||
to be updated. See [charts/Performance & Size](../../../../charts/index.md).
|
||||
|
||||
### Old sensitive tickets
|
||||
|
||||
Unset the "sensitive" flag on old tickets. For example, on tickets that were
|
||||
fixed two or more releases ago.
|
||||
|
||||
[Sample ticket query for ICU 65, for tickets fixed in 63 or
|
||||
earlier](https://unicode-org.atlassian.net/issues/?jql=project%20%3D%20ICU%20AND%20Level%3DSensitive%20AND%20fixVersion%20not%20in%20(65.1%2C%2064.2%2C%2064.1)%20AND%20status%3DDone).
|
||||
Adjust the fixVersion selection as appropriate. Check the list in the ICU
|
||||
meeting.
|
||||
|
||||
Check duplicates and fixedbyotherticket! Keep the "sensitive" flag on tickets
|
||||
that were closed as duplicates of other tickets that are not yet fixed or have
|
||||
been fixed only very recently.
|
||||
|
||||
For removing the flag:
|
||||
|
||||
* Enter bulk edit. Select all query results.
|
||||
* Uncheck duplicates of unfixed or too-recent tickets.
|
||||
* Edit fields:
|
||||
* Security Level = None
|
||||
* Add label "was_sensitive"
|
||||
* No notification emails
|
||||
* Confirm bulk edit.
|
||||
|
||||
---
|
||||
|
||||
## Punt tickets
|
||||
|
||||
Double-check that tickets with commits in this release are closed/fixed. Close
|
||||
as needed. (Hopefully none misticketed at this point...)
|
||||
|
||||
Then punt remaining tickets marked for this release:
|
||||
|
||||
1. In Jira, search for all tickets with Project=ICU, Fix Version=<this
|
||||
release>, Status≠Done.
|
||||
2. Go to Bulk Edit ("..." menu in the upper right corner)
|
||||
3. Select all
|
||||
4. Edit fields:
|
||||
1. Fix Version: replace all with "future"
|
||||
2. Labels: add "punt<this release>" (e.g., "punt63")
|
||||
3. No email notifications
|
||||
5. Confirm bulk edit
|
||||
6. Send a courtesy email to the team with a Jira query URL for the
|
||||
Label="punt<this release>" tickets.
|
||||
|
||||
After punting, please also update the "To-Do for Next ICU Release" widget on
|
||||
Jira.
|
||||
|
||||
1. Open <https://unicode-org.atlassian.net/issues/?filter=10007>
|
||||
2. Use the drop-down to change the fix version to the next ICU version
|
||||
3. Click "Save" next to the filter title
|
||||
|
||||
## Update readme
|
||||
|
||||
Update [ICU4C
|
||||
readme.html](https://github.com/unicode-org/icu/blob/main/icu4c/readme.html)
|
||||
and [ICU4J
|
||||
readme.html](https://github.com/unicode-org/icu/blob/main/icu4j/readme.html)
|
||||
before every milestone (GA / RC / Milestone-N). Make sure the following items
|
||||
are up to date.
|
||||
|
||||
* Release version
|
||||
* Last update date
|
||||
* Description - descriptions for GA, RC and Milesone-N are already included in
|
||||
the readme file.
|
||||
* Comment/uncomment parts as appropriate.
|
||||
* If the readme should remain the same between milestones, we can skip
|
||||
directly to the GA description. Otherwise, pick the right one for the
|
||||
release type.
|
||||
* **Since ICU 67, we have skipped from GA to GA**, without marking &
|
||||
unmarking the readme specifically for the release candidate.
|
||||
* Build steps - make sure supported compiler versions are up to date
|
||||
BIN
docs/processes/release/tasks/publish/maint-63-rc-screenshot.png
Normal file
BIN
docs/processes/release/tasks/publish/maint-63-rc-screenshot.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 74 KiB |
213
docs/processes/release/tasks/release-build.md
Normal file
213
docs/processes/release/tasks/release-build.md
Normal file
|
|
@ -0,0 +1,213 @@
|
|||
---
|
||||
layout: default
|
||||
title: Release Build
|
||||
parent: Release & Milestone Tasks
|
||||
grand_parent: Contributors
|
||||
nav_order: 100
|
||||
---
|
||||
|
||||
<!--
|
||||
© 2021 and later: Unicode, Inc. and others.
|
||||
License & terms of use: http://www.unicode.org/copyright.html
|
||||
-->
|
||||
|
||||
# Release Build
|
||||
{: .no_toc }
|
||||
|
||||
## Contents
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
1. TOC
|
||||
{:toc}
|
||||
|
||||
---
|
||||
|
||||
## Building ICU4J Release Files
|
||||
|
||||
<span style="color:red">*Note: This instruction is reviewed for ICU4J 69.1. Some
|
||||
description may not apply to previous ICU releases. ICU4J library (as of ICU 69)
|
||||
supports JRE 7 or later Java runtime environment. To avoid the Java's system
|
||||
library class's backward compatibility problem, ICU4J binary files must be
|
||||
compiled with Java system libraries from JRE 7.*</span>
|
||||
|
||||
## Prerequisites
|
||||
|
||||
* Java SE Development Kit 8 (to run ant, javac, javadoc..)
|
||||
* Java Runtime Environment 7 (used as bootclasspath for cross-compilation)
|
||||
* Apache Ant 1.10.x (the latest available version)
|
||||
\[<http://ant.apache.org/>\]
|
||||
* JCite 1.13.0 \[<https://arrenbrecht.ch/jcite/>\]
|
||||
|
||||
### Other Prerequisites only for GA
|
||||
|
||||
* Maven Ant Tasks 2.1.3 (GA only) \[<http://maven.apache.org/ant-tasks>\]
|
||||
(Note: This is component is no longer maintained, and ICU project should
|
||||
update the process in near future)
|
||||
* gpg (GNU Privacy Guard)
|
||||
* ICU Project PGP key (icuintl@us.ibm.com - [published to MIT key
|
||||
server](https://pgp.mit.edu/pks/lookup?op=vindex&search=0x44CE7BF2825EA2CD))
|
||||
* Sonatype Nexus Repository Manager account for managing artifacts
|
||||
com.ibm.icu.\* on OSSRH (Reference: [OSSRH
|
||||
Guide](http://central.sonatype.org/pages/ossrh-guide.html))
|
||||
|
||||
<span style="color:red">*Note: Contact Yoshito for the PGP key and Sonatype
|
||||
account.*</span>
|
||||
|
||||
### Configuration
|
||||
|
||||
* Set environment variable `JAVA_HOME` to point to the JDK directory.
|
||||
* Set environment variable `JCITE_DIR` to specify JCite binary location (see[
|
||||
Building ICU4J API Reference Document with
|
||||
JCite](../../../setup/java/ant/index.md))
|
||||
* See `build.properties` to check version strings are properly set.
|
||||
* `api.report.version` / `api.report.prev.version` are used for locating
|
||||
API signature files and should be integer numbers.
|
||||
* `release.file.ver` is used as a part of build output file name.
|
||||
* `api.doc.version` is used for the API document title
|
||||
* `mavne.pom.ver` is used in pom.xml when release files are uploaded to
|
||||
OSSRH
|
||||
|
||||
For ICU 69.1 GA, the contents of the properties file should be:
|
||||
```
|
||||
api.report.version = 69
|
||||
api.report.prev.version = 68
|
||||
release.file.ver = 69_1
|
||||
api.doc.version = 69.1
|
||||
maven.pom.ver = 69.1
|
||||
```
|
||||
|
||||
* Create `build-local.properties` in the ICU4J root directory
|
||||
|
||||
* Edit `build-local.properties` to add a property - `java7.bootclasspath
|
||||
(java6.bootclasspath for ICU57 to ICU62)`
|
||||
|
||||
The value of javaX.bootclasspath should include JRE's system library path. A
|
||||
set of jar files included in the system library path may vary depending on
|
||||
JRE vendor (Oracle, OpenJDK and IBM use different set of jars) and version.
|
||||
The easiest way to get the system library path is to run a simple Java
|
||||
program on the target JRE.
|
||||
|
||||
System.out.println(System.getProperty("sun.boot.class.path"));
|
||||
|
||||
For example, the values on my Linux system (Ubuntu) look like below:
|
||||
|
||||
java7.bootclasspath=/home/yoshito/jdk/oracle/jdk1.7.0_80/jre/lib/resources.jar:/home/yoshito/jdk/oracle/jdk1.7.0_80/jre/lib/rt.jar:/home/yoshito/jdk/oracle/jdk1.7.0_80/jre/lib/sunrsasign.jar:/home/yoshito/jdk/oracle/jdk1.7.0_80/jre/lib/jsse.jar:/home/yoshito/jdk/oracle/jdk1.7.0_80/jre/lib/jce.jar:/home/yoshito/jdk/oracle/jdk1.7.0_80/jre/lib/charsets.jar:/home/yoshito/jdk/oracle/jdk1.7.0_80/jre/lib/jfr.jar:/home/yoshito/jdk/oracle/jdk1.7.0_80/jre/classes
|
||||
|
||||
One Windows system, path separator back slash '\\' should be replaced with
|
||||
forward slash '/'. For example:
|
||||
|
||||
java7.bootclasspath=C:/jdk/oracle/7u80/jre/lib/resources.jar;C:/jdk/oracle/7u80/jre/lib/rt.jar;C:/jdk/oracle/7u80/jre/lib/sunrsasign.jar;C:/jdk/oracle/7u80/jre/lib/jsse.jar;C:/jdk/oracle/7u80/jre/lib/jce.jar;C:/jdk/oracle/7u80/jre/lib/charsets.jar;C:/jdk/oracle/7u80/jre/lib/jfr.jar;C:/jdk/oracle/7u80/jre/classes
|
||||
|
||||
### Additional Configuration for GA
|
||||
|
||||
* Add 2 more properties to `build-local.properties`
|
||||
* `maven-ant-tasks.jar` - Specify the path to the Maven Ant Tasks jar
|
||||
file.
|
||||
* `gpg.user` - Specify the ICU Project PGP key user name
|
||||
|
||||
For example, build-local.properties look like below:
|
||||
|
||||
```
|
||||
java7.bootclasspath=/home/yoshito/jdk/oracle/jdk1.7.0_80/jre/lib/resources.jar:/home/yoshito/jdk/oracle/jdk1.7.0_80/jre/lib/rt.jar:/home/yoshito/jdk/oracle/jdk1.7.0_80/jre/lib/sunrsasign.jar:/home/yoshito/jdk/oracle/jdk1.7.0_80/jre/lib/jsse.jar:/home/yoshito/jdk/oracle/jdk1.7.0_80/jre/lib/jce.jar:/home/yoshito/jdk/oracle/jdk1.7.0_80/jre/lib/charsets.jar:/home/yoshito/jdk/oracle/jdk1.7.0_80/jre/lib/jfr.jar:/home/yoshito/jdk/oracle/jdk1.7.0_80/jre/classes
|
||||
maven-ant-tasks.jar = /home/yoshito/java-libs/maven-ant-tasks/maven-ant-tasks-2.1.3.jar
|
||||
gpg.user = ICU Project
|
||||
```
|
||||
|
||||
<span style="color:red">*Note: Maven Ant Tasks is no longer maintained. ICU team should find out another method to publish ICU artifacts to the repository (ticket [ICU-12811](https://unicode-org.atlassian.net/browse/ICU-12811)).*</span>
|
||||
|
||||
* Create maven local setting file `$HOME/.m2/settings.xml` if absent. Then add
|
||||
the Sonatype Nexus Repository Manager account information in the file. For
|
||||
example:
|
||||
```xml
|
||||
<settings>
|
||||
<servers>
|
||||
<server>
|
||||
<id>icu4j-releases</id>
|
||||
<username>yumaoka</username>
|
||||
<password>OSSRH-SonaType-Password</password>
|
||||
</server>
|
||||
<server>
|
||||
<id>icu4j-snapshots</id>
|
||||
<username>yumaoka</username>
|
||||
<password>OSSRH-SonaType-Password</password>
|
||||
</server>
|
||||
</servers>
|
||||
</settings>
|
||||
```
|
||||
|
||||
### Building Release Files for Milestones/Release Candidates
|
||||
|
||||
1. Checkout tagged version - Use clean checkout of Git (SVN up to ICU62) tag
|
||||
(e.g. release-61-0-1, release-61-rc..) for building release files.
|
||||
2. Run `$ ant releaseVer` - This build target generates ICU release files with
|
||||
version number in a folder `release` under the ICU4J root directory.
|
||||
|
||||
This ant target prints out warning messages as below if the build system is
|
||||
not properly configured.
|
||||
```
|
||||
_verify_config_for_release:
|
||||
[echo] ################################################################
|
||||
[echo] [WARNING] Insufficient Build Configuration for ICU4J Release
|
||||
[echo] JDK Tools Version: 1.8.0_152
|
||||
[echo] JRE 7 System Library Path: Not Defined!
|
||||
[echo] JCite Library Path: /home/yoshito/java-libs/jcite-1.13.0/build/jcite.jar:/home/yoshito/java-libs/jcite-1.13.0/lib/commons-discovery-0.4.jar:/home/yoshito/java-libs/jcite-1.13.0/lib/commons-logging-1.1.jar:/home/yoshito/java-libs/jcite-1.13.0/lib/java2html.jar`
|
||||
[echo] ################################################################
|
||||
|
||||
BUILD SUCCESSFUL
|
||||
Total time: 5 minutes 31 seconds
|
||||
```
|
||||
If you see such warnings at the end of build log, fix the issue and run the
|
||||
target again.
|
||||
3. Upload all files generated under the `release` directory to the ICU site.
|
||||
|
||||
## Building Release Files for Final Release (GA)
|
||||
|
||||
A final (official) release files will be posted to the Maven Central Repository
|
||||
as well as the ICU project site. The build target `releaseFinal` generates all
|
||||
necessary files for the Maven repository and upload them after regular release
|
||||
build target is executed.
|
||||
1. Checkout tagged version - Use clean checkout of Git (SVN up to ICU62) tag
|
||||
(e.g. release-61-1, release-61-2) for building release files.
|
||||
2. Run `$ ant releaseVer` once to make sure there are no build configuration
|
||||
issues. Run `$ ant clean` to clean up build.
|
||||
3. \[Optional\] In the next step, the build target invokes gpg to generate
|
||||
signature of build output files. gpg will request you to type in the
|
||||
passphrase for the ICU Project (icuintl@us.ibm.com) PGP key once. gpg
|
||||
pinentry is used for this purpose, but it may not work well on some systems
|
||||
when pgp was invoked from ant (such as Mac OS X). If this is the case, you
|
||||
would want to run gpg-agent to cache passphrase. More specifically, once you
|
||||
set up gpg-agent, run `$ gpg -ab -u "ICU Project" foo.txt` to sign arbitrary
|
||||
file. This operation will prompt you to type in the ICU Project key's
|
||||
passphrase and cache it. So it does not need to ask you to type passphrase
|
||||
again while running the ant release target.
|
||||
4. Run `$ ant releaseFinal` . This target generates release files for ICU site,
|
||||
as well as files for Maven Central Repository, then upload the files to OSSRH
|
||||
staging repository. You should see build log as below at the end.
|
||||
```
|
||||
[deploy] Transferring 37K from icu4j-releases
|
||||
[deploy] Uploaded 37K
|
||||
[deploy] Uploading: com/ibm/icu/icu4j-localespi/61.1/icu4j-localespi-61.1-sources.jar.asc to repository icu4j-releases at https://oss.sonatype.org/service/local/staging/deploy/maven2
|
||||
[deploy] Transferring 0K from icu4j-releases
|
||||
[deploy] Uploaded 0K
|
||||
[deploy] Uploading: com/ibm/icu/icu4j-localespi/61.1/icu4j-localespi-61.1-javadoc.jar to repository icu4j-releases at https://oss.sonatype.org/service/local/staging/deploy/maven2
|
||||
[deploy] Transferring 22K from icu4j-releases
|
||||
[deploy] Uploaded 22K
|
||||
[deploy] Uploading: com/ibm/icu/icu4j-localespi/61.1/icu4j-localespi-61.1-javadoc.jar.asc to repository icu4j-releases at https://oss.sonatype.org/service/local/staging/deploy/maven2
|
||||
[deploy] Transferring 0K from icu4j-releases
|
||||
[deploy] Uploaded 0K
|
||||
|
||||
BUILD SUCCESSFUL
|
||||
Total time: 6 minutes 19 seconds
|
||||
```
|
||||
After the successful target execution, copy files generated under `release`
|
||||
directory and upload them to ICU site.
|
||||
5. Log on to [OSSRH Nexus Repository Manager](https://oss.sonatype.org/). Select
|
||||
"Staging Repositories" under "Build Promotion" on the left navigation pane,
|
||||
then type "com.ibm.icu" on the search field on the upper right corner. You
|
||||
should find a repository entry corresponding to the one just uploaded. Select
|
||||
the entry, and sanity check content. Once you confirm the contents, click
|
||||
"Close" on the menu. If the repository is closed successfully, you can
|
||||
"Release" after that. The release operation will promote the staging
|
||||
repository to production. It usually takes 20 to 30 minutes.
|
||||
|
||||
|
||||
89
docs/processes/release/tasks/standards.md
Normal file
89
docs/processes/release/tasks/standards.md
Normal file
|
|
@ -0,0 +1,89 @@
|
|||
---
|
||||
layout: default
|
||||
title: Standards Update
|
||||
parent: Release & Milestone Tasks
|
||||
grand_parent: Contributors
|
||||
nav_order: 110
|
||||
---
|
||||
|
||||
<!--
|
||||
© 2021 and later: Unicode, Inc. and others.
|
||||
License & terms of use: http://www.unicode.org/copyright.html
|
||||
-->
|
||||
|
||||
# Standards Updates
|
||||
{: .no_toc }
|
||||
|
||||
## Contents
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
1. TOC
|
||||
{:toc}
|
||||
|
||||
---
|
||||
|
||||
## Time Zones
|
||||
|
||||
Make sure the timezone (Olson) data is up to date.
|
||||
|
||||
Olson timezone data should be regularly updated in the trunk. If the data is out
|
||||
of date, follow the instruction described in the
|
||||
[readme](https://github.com/unicode-org/icu-data/blob/main/tzdata/readme.txt)
|
||||
file.
|
||||
|
||||
Once the timezone resource file is generated by the process above, the file
|
||||
should be checked into
|
||||
[zoneinfo64.txt](https://github.com/unicode-org/icu/blob/main/icu4c/source/data/misc/zoneinfo64.txt)
|
||||
in the trunk.
|
||||
|
||||
## Unicode
|
||||
|
||||
### Update Unicode Data
|
||||
|
||||
See the [Unicode Update page](../../unicode-update.md) and the instructions in
|
||||
[icu4c/source/data/unidata/changes.txt](https://github.com/unicode-org/icu/blob/main/icu4c/source/data/unidata/changes.txt)
|
||||
and nearby files, also check the change log for this and related files such as
|
||||
UnicodeData.txt.
|
||||
|
||||
### Update script code enums
|
||||
|
||||
Update script code enums with new codes from ISO 15924, send a notice for them
|
||||
as public API (born `@stable`) to the icu-design list.
|
||||
|
||||
Starting with ICU 55, add script code enum constants only after assignment of
|
||||
Unicode script property value aliases; otherwise the names of the constants may
|
||||
become confusing.
|
||||
|
||||
Soon after a Unicode release, work to assign property value aliases for scripts
|
||||
that are known to be added in the next version, then update ICU.
|
||||
|
||||
Constants for script codes like Latf and Aran that are not subject to separate
|
||||
encoding may be added at any time.
|
||||
|
||||
See details in
|
||||
[icu4c/source/data/unidata/changes.txt](https://github.com/unicode-org/icu/blob/main/icu4c/source/data/unidata/changes.txt)
|
||||
and keep the list of script codes not yet in ICU up to date there.
|
||||
|
||||
For new codes see <http://www.unicode.org/iso15924/codechanges.html> (check for
|
||||
recent changes with the code highlighted in the left column and "Add" in the
|
||||
right column) and <http://www.iana.org/assignments/language-subtag-registry>
|
||||
(Search for "Type: script" and look for recent "Added:" dates.) Discuss what to
|
||||
do if these two sources are out of sync.
|
||||
|
||||
## CLDR
|
||||
|
||||
### Sync ICU with CLDR and tag CLDR.
|
||||
|
||||
Update ICU data from CLDR, tag CLDR. Instructions
|
||||
[here](https://github.com/unicode-org/icu/blob/main/icu4c/source/data/cldr-icu-readme.txt).
|
||||
|
||||
### Update MeasureUnit Code
|
||||
|
||||
<https://github.com/unicode-org/icu/blob/main/docs/processes/release/tasks/updating-measure-unit.md>
|
||||
|
||||
## ISO 4217 numeric codes
|
||||
|
||||
Make sure the ISO 4217 numeric code mapping data is up to date.
|
||||
|
||||
See the instruction in
|
||||
<https://github.com/unicode-org/icu/blob/main/tools/currency/readme.txt>
|
||||
|
|
@ -1,9 +1,26 @@
|
|||
---
|
||||
layout: default
|
||||
title: Updating MeasureUnit with new CLDR data
|
||||
parent: Release & Milestone Tasks
|
||||
grand_parent: Contributors
|
||||
nav_order: 120
|
||||
---
|
||||
|
||||
<!--
|
||||
© 2020 and later: Unicode, Inc. and others.
|
||||
License & terms of use: http://www.unicode.org/copyright.html
|
||||
-->
|
||||
|
||||
# Updating Measure Unit with new CLDR data
|
||||
# Updating MeasureUnit with new CLDR data
|
||||
{: .no_toc }
|
||||
|
||||
## Contents
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
1. TOC
|
||||
{:toc}
|
||||
|
||||
---
|
||||
|
||||
This document explains how to update the C++ and Java version of the MeasureUnit
|
||||
class with new CLDR data.
|
||||
|
|
|
|||
304
docs/processes/release/tasks/versions.md
Normal file
304
docs/processes/release/tasks/versions.md
Normal file
|
|
@ -0,0 +1,304 @@
|
|||
---
|
||||
layout: default
|
||||
title: Version Numbers
|
||||
parent: Release & Milestone Tasks
|
||||
grand_parent: Contributors
|
||||
nav_order: 140
|
||||
---
|
||||
|
||||
<!--
|
||||
© 2021 and later: Unicode, Inc. and others.
|
||||
License & terms of use: http://www.unicode.org/copyright.html
|
||||
-->
|
||||
|
||||
# Version Numbers
|
||||
{: .no_toc }
|
||||
|
||||
## Contents
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
1. TOC
|
||||
{:toc}
|
||||
|
||||
---
|
||||
|
||||
## ICU Version Number
|
||||
|
||||
For reference, see the section in the User Guide about Version numbers here:
|
||||
|
||||
<http://userguide.icu-project.org/design#TOC-Version-Numbers-in-ICU>
|
||||
|
||||
### ICU Data
|
||||
|
||||
[icu4c/source/data/misc/icuver.txt](https://github.com/unicode-org/icu/blob/main/icu4c/source/data/misc/icuver.txt)
|
||||
needs to be updated with the correct version number for ICU and its data.
|
||||
|
||||
#### Since ICU 68
|
||||
|
||||
In
|
||||
[tools/cldr/cldr-to-icu/build-icu-data.xml](https://github.com/unicode-org/icu/blob/main/tools/cldr/cldr-to-icu/build-icu-data.xml)
|
||||
edit `<property name="icuVersion" value="67.1.0.0"/>` and `<property
|
||||
name="icuDataVersion" value="67.1.0.0"/>`.
|
||||
|
||||
The CLDR-to-ICU converter will then generate icuver.txt with the new version
|
||||
numbers.
|
||||
|
||||
Run the converter, or coordinate with the person who will run it.
|
||||
|
||||
#### Until ICU 67 (inclusive)
|
||||
|
||||
Edit icuver.txt directly.
|
||||
|
||||
### ICU4C
|
||||
|
||||
1. The instructions for updating the version number are in
|
||||
[icu4c/source/common/unicode/uvernum.h](https://github.com/unicode-org/icu/blob/main/icu4c/source/common/unicode/uvernum.h).
|
||||
2. [icu4c/source/stubdata/stubdata.vcxproj](https://github.com/unicode-org/icu/blob/main/icu4c/source/stubdata/stubdata.vcxproj)
|
||||
and
|
||||
[icu4c/source/data/makedata.mak](https://github.com/unicode-org/icu/blob/main/icu4c/source/data/makedata.mak)
|
||||
may also need to updated with the correct version for icudt.
|
||||
3. After uvernum.h is updated, the Windows project files should be updated by
|
||||
running the UNIX makefile target '**update-windows-makefiles**' in
|
||||
icu/source.
|
||||
* You will need to rerun "./configure" first though before you can run the
|
||||
command "make update-windows-makefiles".
|
||||
* Note: You can use MSYS+MinGW to run the UNIX makefile on Windows
|
||||
platforms as well.
|
||||
4. As well, the ICU4C "configure" script should be updated so that it reflects
|
||||
the latest version number.
|
||||
* Note: When updating the version number in the configure files be careful
|
||||
not to just blindly search-and-replace the version number.
|
||||
For example, there are lines like this: "As of ICU 62, both C and C++
|
||||
files require them" which need to have the exact version number
|
||||
retained.
|
||||
|
||||
### ICU4J
|
||||
|
||||
Since ICU4J 4.6, you can quickly check the current version information by
|
||||
running jar main in icu4j.jar. For example,
|
||||
|
||||
```sh
|
||||
$ java -jar icu4j.jar
|
||||
```
|
||||
|
||||
prints out -
|
||||
|
||||
<pre>
|
||||
International Component for Unicode for Java 4.8
|
||||
Implementation Version: 4.8
|
||||
Unicode Data Version: 6.0
|
||||
CLDR Data Version: 2.0
|
||||
Time Zone Data Version: 2011g
|
||||
</pre>
|
||||
|
||||
For updating ICU version numbers, follow the steps below.
|
||||
|
||||
1. [icu4j/main/shared/build/common.properties](https://github.com/unicode-org/icu/blob/main/icu4j/main/shared/build/common.properties)
|
||||
|
||||
* icu4j.spec.version: This is API spec version, therefore, 2-digit major
|
||||
version only. The version number won't be changed for maintenance
|
||||
releases. (e.g. "55")
|
||||
* icu4j.impl.version: This version is used for the actual release version,
|
||||
including maintenance release numbers. (e.g. "55.1"). Note: We do not
|
||||
use .0 - For example, ICU4J 54.1 uses "54.1", instead of "54.1.0" For
|
||||
milestone 1, use <major>.0.1 (e.g. 60.0.1).
|
||||
* icu4j.data.version: This version number is corresponding to the data
|
||||
structure, therefore, won't be changed in maintenance releases. Use
|
||||
2-digit number used by the data path. (e.g. "55")
|
||||
* \[*Not applicable for ICU4J 60+*\] current.year: Some build script embed
|
||||
the year taken from this into a copyright template. Make sure this value
|
||||
is updated to the current year for a new release (also applicable to a
|
||||
maintenance release).
|
||||
|
||||
2. icu4j/build.properties (For API change report and release target)
|
||||
|
||||
* api.report.version: 2 digit release number. Note: If necessary, we may
|
||||
include maintenance release number. (e.g "54", "481")
|
||||
* api.report.prev.version: The previous version compared against the current
|
||||
version. (e.g. "46")
|
||||
* release.file.ver: This string is used for files names. For milestone
|
||||
releases, use <2-digit major version> + "m" + <milestone number>, e.g.
|
||||
"55m1". For release candidate, use <2-digit major version> + "rc", e.g.
|
||||
54rc. For official releases, use full version numbers using under bar as the
|
||||
separator, e.g. "54_1", "54_1_1".
|
||||
* api.doc.version: The version displayed in API reference doc - use full
|
||||
version number such as "60.1" for official releases, "60 Milestone 1" for
|
||||
milestone 1.
|
||||
* maven.pom.ver: The version used in ICU pom.xml files. Use full version
|
||||
number such as "60.1" for official releases, "61.1-SNAPSHOT" until 61.1
|
||||
release, after 60.1.
|
||||
|
||||
3. [icu4j/main/classes/core/src/com/ibm/icu/util/VersionInfo.java](https://github.com/unicode-org/icu/blob/main/icu4j/main/classes/core/src/com/ibm/icu/util/VersionInfo.java)
|
||||
|
||||
There is a static block starting at line 501 (as of 54.1) in the source file -
|
||||
|
||||
<pre>
|
||||
/**
|
||||
* Initialize versions only after MAP_ has been created
|
||||
*/
|
||||
static {
|
||||
UNICODE_1_0 = getInstance(1, 0, 0, 0);
|
||||
UNICODE_1_0_1 = getInstance(1, 0, 1, 0);
|
||||
UNICODE_1_1_0 = getInstance(1, 1, 0, 0);
|
||||
UNICODE_1_1_5 = getInstance(1, 1, 5, 0);
|
||||
UNICODE_2_0 = getInstance(2, 0, 0, 0);
|
||||
UNICODE_2_1_2 = getInstance(2, 1, 2, 0);
|
||||
UNICODE_2_1_5 = getInstance(2, 1, 5, 0);
|
||||
UNICODE_2_1_8 = getInstance(2, 1, 8, 0);
|
||||
UNICODE_2_1_9 = getInstance(2, 1, 9, 0);
|
||||
UNICODE_3_0 = getInstance(3, 0, 0, 0);
|
||||
UNICODE_3_0_1 = getInstance(3, 0, 1, 0);
|
||||
UNICODE_3_1_0 = getInstance(3, 1, 0, 0);
|
||||
UNICODE_3_1_1 = getInstance(3, 1, 1, 0);
|
||||
UNICODE_3_2 = getInstance(3, 2, 0, 0);
|
||||
UNICODE_4_0 = getInstance(4, 0, 0, 0);
|
||||
UNICODE_4_0_1 = getInstance(4, 0, 1, 0);
|
||||
UNICODE_4_1 = getInstance(4, 1, 0, 0);
|
||||
UNICODE_5_0 = getInstance(5, 0, 0, 0);
|
||||
UNICODE_5_1 = getInstance(5, 1, 0, 0);
|
||||
UNICODE_5_2 = getInstance(5, 2, 0, 0);
|
||||
UNICODE_6_0 = getInstance(6, 0, 0, 0);
|
||||
UNICODE_6_1 = getInstance(6, 1, 0, 0);
|
||||
UNICODE_6_2 = getInstance(6, 2, 0, 0);
|
||||
UNICODE_6_3 = getInstance(6, 3, 0, 0);
|
||||
UNICODE_7_0 = getInstance(7, 0, 0, 0);
|
||||
<b>
|
||||
ICU_VERSION = getInstance(54, 1, 0, 0);
|
||||
ICU_DATA_VERSION = getInstance(54, 1, 0, 0);</b>
|
||||
UNICODE_VERSION = UNICODE_7_0;
|
||||
|
||||
UCOL_RUNTIME_VERSION = getInstance(8);
|
||||
UCOL_BUILDER_VERSION = getInstance(9);
|
||||
UCOL_TAILORINGS_VERSION = getInstance(1);
|
||||
}
|
||||
</pre>
|
||||
|
||||
In the same file, starting at line 164 (as of 54.1) -
|
||||
|
||||
<pre>
|
||||
/**
|
||||
* Data version string for ICU's internal data.
|
||||
* Used for appending to data path (e.g. icudt43b)
|
||||
* @internal
|
||||
* @deprecated This API is ICU internal only.
|
||||
*/
|
||||
@Deprecated
|
||||
public static final String <b>ICU_DATA_VERSION_PATH = "54b";</b>
|
||||
</pre>
|
||||
|
||||
4. [icu4j/pom.xml](http://source.icu-project.org/repos/icu/trunk/icu4j/pom.xml)
|
||||
(before ICU4J 60 only)
|
||||
|
||||
<pre>
|
||||
<groupId>com.ibm.icu</groupId>
|
||||
<artifactId>icu4j</artifactId>
|
||||
<version><b>55-SNAPSHOT</b></version>
|
||||
<name>ICU4J</name>
|
||||
</pre>
|
||||
|
||||
Only for the final release (including maintenance release), update the <version>
|
||||
item to the actual release version (e.g. "54.1", "4.8.1") Otherwise, use (next
|
||||
ver)-SNAPSHOT. (e.g. "55-SNAPSHOT").
|
||||
|
||||
5. Time Bombs (before ICU4J 52)
|
||||
|
||||
***Note: We no longer use time bombs since ICU4J 52. In the trunk,
|
||||
logKnownIssue() is used for skipping known test failures. The new scheme no
|
||||
longer depends on the current ICU4J version, so there are no updates
|
||||
necessary in test codes when version number is updated. See [Skipping Known
|
||||
Test Failures](../../../setup/eclipse/time.md) for more details.***
|
||||
|
||||
There might be some test cases intentionally skipped for the current ICU4J
|
||||
version. When ICU4J version is updated, these time bombed test cases may
|
||||
show up. In this case, you should:
|
||||
|
||||
* Inform the list of failing test cases because of the version change to
|
||||
icu-core ML - ask if someone has plan to fix them.
|
||||
* File a ticket if a time bomb does not have any corresponding Jira ticket
|
||||
and put the ticket number as comment
|
||||
* Move the time bomb version to the next milestone.
|
||||
|
||||
The time bomb looks like below -
|
||||
|
||||
<pre>
|
||||
if (<b>isICUVersionBefore(49, 1)</b>) { // ICU-6806
|
||||
logln(showOrderComparison(uLocale, style1, style2, order1, order2));
|
||||
} else {
|
||||
errln(showOrderComparison(uLocale, style1, style2, order1, order2));
|
||||
}
|
||||
</pre>
|
||||
|
||||
Note: ICU4J time bomb - Before
|
||||
[ICU-7973](https://unicode-org.atlassian.net/browse/ICU-7973), we used to
|
||||
use skipIfBeforeICU(int,int,int).
|
||||
|
||||
When a test case with time bomb still fails before a major release, the time
|
||||
bomb may be moved to the version before the first milestone of the next
|
||||
major release stream. For example, the time bomb (49,1) is not yet resolved
|
||||
before ICU4J 49 release, it should be updated to (50,0,1). This will prevent
|
||||
the error test case showing up during 49 maintenance releases, and appear
|
||||
before the first milestone of 50.0.1.
|
||||
|
||||
6. ICU4J Eclipse plug-in version (Eclipse release only)
|
||||
|
||||
ICU4J Eclipse plug-in use the standard Eclipse versioning scheme -
|
||||
X.Y.Z.v<build date>, for example, com.ibm.icu_4.2.1.v20100412.jar. By
|
||||
default, the build script compose the version string from
|
||||
icu4j.plugin.impl.version.string property in
|
||||
[eclipse-build/build.properties](https://github.com/unicode-org/icu/blob/main/icu4j/eclipse-build/build.properties)
|
||||
with current date at the build time. However, when we tag a version, we want
|
||||
to freeze the build date part. To force a fixed version string, we add a
|
||||
property - icu4j.eclipse.build.version.string in the build.properties. For
|
||||
example, see
|
||||
[tags/release-4-4-2-eclipse37-20110208/eclipse-build/build.properties](http://source.icu-project.org/repos/icu/tags/icu4j/release-4-4-2-eclipse37-20110208/eclipse-build/build.properties).
|
||||
|
||||
7. [DebugUtilitiesData.java](https://github.com/unicode-org/icu/blob/main/icu4j/main/tests/core/src/com/ibm/icu/dev/test/util/DebugUtilities.java)
|
||||
|
||||
This file is automatically generated when data is generated for ICU4J. The
|
||||
ICU4C version number string should be check to ensure that the correct
|
||||
version number is being used. public static final String
|
||||
ICU4C_VERSION="50.0.2"; Note: The ICU4C version number string in this JAVA
|
||||
file is not really used for anything except for a few logln method calls.
|
||||
Perhaps this member is not really needed.
|
||||
|
||||
## Data Versions
|
||||
|
||||
Make sure data file versions (for **data contents**) are properly assigned.
|
||||
|
||||
If any of the data files in the
|
||||
[/icu/source/data/](https://github.com/unicode-org/icu/tree/main/icu4c/source/data)
|
||||
directory has changed **MANUALLY**, upgrade the version number accordingly as
|
||||
well. If the contents of a resource bundle has changed, then increase the
|
||||
version number (at least the minor version field). The CLDR generated data
|
||||
should have the correct number. **Note** from Markus (20090514, ICU 4.2
|
||||
timeframe): Most data files automatically get their version numbers set by the
|
||||
LDML2ICUConverter, from CLDR version numbers. It is not clear what, if anything,
|
||||
needs to be done for this task.
|
||||
|
||||
The ICU4J data files depend on the ICU4C data files. Thus, in order to
|
||||
regenerate the updated ICU4J data files, you will first need to update the ICU4C
|
||||
data files version.
|
||||
|
||||
Once the ICU4C data files are updated, follow the instructions in the Readme
|
||||
file here:
|
||||
<https://github.com/unicode-org/icu/blob/main/icu4c/source/data/icu4j-readme.txt>
|
||||
|
||||
## Data File *Format* Versions
|
||||
|
||||
Make sure data file **format** versions are updated. See
|
||||
<http://userguide.icu-project.org/icudata#TOC-ICU-Data-File-Formats>
|
||||
|
||||
For Unicode data files, it is also useful to look at recent tools-tree changes:
|
||||
[icu/commits/main/tools/unicode](https://github.com/unicode-org/icu/commits/main/tools/unicode)
|
||||
|
||||
If the format of a binary data file has changed, upgrade the format version in
|
||||
the UDataInfo header for that file. Better: Change the format version
|
||||
immediately when the format is changed. The change must be made in both the
|
||||
producer/generator and consumer/runtime code.
|
||||
|
||||
It is desirable to maintain backward compatibility, but sometimes impractical.
|
||||
Update the major version number for incompatible changes. Runtime code should
|
||||
permit higher minor version numbers for supported major versions.
|
||||
|
||||
We rarely use the third and fourth version number fields, except for UTrie (only
|
||||
version 1, not UTrie2) parameters that don't really change.
|
||||
97
docs/processes/unicode-update.md
Normal file
97
docs/processes/unicode-update.md
Normal file
|
|
@ -0,0 +1,97 @@
|
|||
---
|
||||
layout: default
|
||||
title: Unicode Update
|
||||
parent: Release & Milestone Tasks
|
||||
grand_parent: Contributors
|
||||
nav_order: 130
|
||||
---
|
||||
|
||||
<!--
|
||||
© 2021 and later: Unicode, Inc. and others.
|
||||
License & terms of use: http://www.unicode.org/copyright.html
|
||||
-->
|
||||
|
||||
# Unicode Update
|
||||
{: .no_toc }
|
||||
|
||||
## Contents
|
||||
{: .no_toc .text-delta }
|
||||
|
||||
1. TOC
|
||||
{:toc}
|
||||
|
||||
---
|
||||
|
||||
*[This page's last thorough update was on [5 August
|
||||
2010](https://sites.google.com/site/icusite/system/app/pages/admin/revisions?wuid=wuid:gx:6c0edddbaea77d12).]*
|
||||
<!-- TODO: move into release/tasks/ if that's where it belongs? Else update the nav info. -->
|
||||
|
||||
The International Components for Unicode (ICU) implement the Unicode Standard
|
||||
and many of its Standard Annexes faithfully and are updated to a new Unicode
|
||||
version soon after its release. Usually, the ICU team participates in the
|
||||
Unicode beta process by updating to a new Unicode version in a branch and
|
||||
testing it thoroughly. In the past, this has uncovered problems that could be
|
||||
fixed before the release of the new Unicode version.
|
||||
|
||||
One notable exception to ICU implementing all of Unicode is that it does not
|
||||
provide any access to Unihan data (mostly because of low demand and the large
|
||||
size of the Unihan data).
|
||||
|
||||
## Update process
|
||||
|
||||
For the last several updates, there is a [change log
|
||||
here](https://github.com/unicode-org/icu/blob/main/icu4c/source/data/unidata/changes.txt).
|
||||
In short, most of the ucd .txt files are copied into the ICU repository, either
|
||||
without modification or, for some files, with comments removed and lines merged
|
||||
to reduce their size.
|
||||
|
||||
Some of the data files are not part of the Unicode release but are output from
|
||||
Mark's Unicode tools. See <http://sites.google.com/site/unicodetools/>
|
||||
|
||||
Note: We have looked at using the [UCD
|
||||
XML](http://www.unicode.org/ucd/#UCDinXML) files, but did not want to rely on
|
||||
them alone until there was a way to verify that they contain precisely the same
|
||||
data as the .txt files. Also, using the XML files would require a partial
|
||||
rewrite of the existing tools. (There was an outdated, experimental, partial UCD
|
||||
XML parser here:
|
||||
<https://github.com/unicode-org/icu-docs/tree/main/design/properties/genudata>)
|
||||
|
||||
The ICU Unicode tools parse the text files, process the data somewhat, and write
|
||||
binary data for runtime use. Most of these tools live in a [source
|
||||
tree](https://github.com/unicode-org/icu/tree/main/tools/unicode) separate
|
||||
from the ICU4C/ICU4J sources, and link with ICU4C.
|
||||
|
||||
The following steps are necessarily manual:
|
||||
|
||||
* New property values and properties need to be reviewed.
|
||||
* For new property values, enum constants are added to the API.
|
||||
* For new properties, APIs are added and the tools are modified to write the
|
||||
additional data into new fields in the data structures; sometimes new data
|
||||
structures need to be developed for new properties.
|
||||
* Some new properties are not exposed via simple, direct data access APIs but
|
||||
in more high-level APIs (like case mapping and normalization functions).
|
||||
* Sometimes changes in which property aliases are canonical vs. actual aliases
|
||||
require manual changes to helper files or tools.
|
||||
|
||||
New properties (whether they are supported via dedicated API or not) should be
|
||||
added to the [Properties User Guide
|
||||
chapter](http://userguide.icu-project.org/strings/properties).
|
||||
|
||||
## Testing
|
||||
|
||||
The ICU test suites include some tests for Unicode data. Some just check the
|
||||
data from the API against the original .txt files. Some tests simply check for
|
||||
certain hardcoded values, which have to be updated when those values change
|
||||
deliberately. Other tests perform consistency checks between some properties, or
|
||||
between different implementations.
|
||||
|
||||
There is a program as a part of CLDR that uses regular expressions to test the
|
||||
segmentation rules and properties (LineBreak, WordBreak, etc). That is, there is
|
||||
a regular expression corresponding to each of the rules, and a brute force
|
||||
evaluation of them. That is used to generate the tables and test data. The
|
||||
segmentation rules in ICU are later modified by hand to match the
|
||||
specifications. That has to be done by hand, because there are some areas where
|
||||
the rules don't correspond 1:1 with the spec. There are a series of ICU
|
||||
consistency tests for those rules. ICU also includes regression tests with
|
||||
"golden files" that are used to detect unanticipated side effects of revisions
|
||||
to the rules.
|
||||
|
|
@ -171,8 +171,9 @@ The simplest way to ensure that
|
|||
transitive dependency versions are included correctly is to just specify the
|
||||
`github-pages` gem. This is already configured in `Gemfile` in the root
|
||||
directory. Thus, to ensure that the Ruby shell has the correct versions of
|
||||
dependencies downloaded and cached, in the root directory, run:
|
||||
dependencies downloaded and cached, in the root directory (`/docs`), run:
|
||||
```bash
|
||||
cd <ICU>/docs # change to User Guide docs root directory
|
||||
bundle update
|
||||
```
|
||||
|
||||
|
|
@ -196,4 +197,4 @@ will be available at <http://localhost:4000/icu/>.
|
|||
## Previous version
|
||||
|
||||
The previous version of the ICU User Guide has been maintained via Google Sites. The Site
|
||||
address is <http://sites.google.com/site/icuprojectuserguide/>
|
||||
address is <http://sites.google.com/site/icuprojectuserguide/>
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue