documents/process/graduation.md

Graduating Components from Experimental
=======================================

This document contains a checklist for the requirements to migrate a component from experimental.

- [ ] The crate should fully conform with the [ICU4X Style Guide](https://github.com/unicode-org/icu4x/blob/main/documents/process/style_guide.md):
  - [ ] The crate should have a complete library header as shown in [boilerplate.md](https://github.com/unicode-org/icu4x/blob/main/documents/process/boilerplate.md) with Clippy passing
  - [ ] The names of exported types should conform to the recommendations in the Style Guide
  - [ ] All Error types should be `Copy`
  - [ ] All constructors should take options structs by value
  - [ ] All constructors should take arguments in the following order: Provider, Locale, Options
  - [ ] All constructors should have the standard set of overloads for provider types
  - [ ] Runtime dependencies should be minimal and able to be disabled with Cargo features if possible
  - [ ] Any `TODO`, `FIXME`, `todo!`, `unimplemented!`, or other placeholders should either be resolved or link to an issue number. (It is okay to ship a small amount of code with tech debt comments, but anything having to do with code correctness should be resolved)
- [ ] The crate should have a conventional Cargo.toml file:
  - [ ] Cargo.toml should use license, not license-file
  - [ ] The description should be useful
  - [ ] Correct repo link, authors, categories, include
  - [ ] Correct docs.rs and cargo-all-features metadata settings
  - [ ] A `rust-version` field with the MSRV of this crate in accordance with the current ICU4X policies on MSRV.
  - [ ] The crate should have an `std` feature if (and only if) it contains code that depends on `std`, such as file I/O or implementing the Error trait
  - [ ] Audit all features so that any `foo/bar` in a feature is `foo?/bar` when `foo` is an optional dep; if you intend to enable `foo`, add two entries
  - [ ] Use `dep:` for enabling dependencies
- [ ] The crate should be fully documented
  - [ ] Every exported function should have docs coverage
  - [ ] There should be a crate-level example that illustrates a common use case for the component with the heading `# Examples`
  - [ ] All options and conditional code paths should have a corresponding docs test with the heading `# Examples`
  - [ ] All functions that are conditional on a Cargo feature should say so (last line before `# Examples`): ```✨ *Enabled with the `alloc` Cargo feature.*```
  - [ ] Compiled data constructors should say "with compiled data" in the first sentence and should have a Cargo feature alert following the above syntax.
- [ ] The APIs should follow ICU4X style
  - [ ] All options bags should be `Copy` (and contain references if they need to). Exceptions can be made by discussion.
  - [ ] All options bags and their relevant options must be in an `options` module ([#5991](https://github.com/unicode-org/icu4x/issues/5991))
  - [ ] If there is a Borrowed type, then compiled data constructors like `Foo::new()` must return `FooBorrowed` ([#5440](https://github.com/unicode-org/icu4x/issues/5440))
  - [ ] Options bag enum fields should consistently be wrapped in an `Option`, ideally with a better-named default/"auto" variant ([#5488](https://github.com/unicode-org/icu4x/issues/5488))
- [ ] The data structs should fully follow ZeroVec style
  - [ ] Deserialization should not have a "zero-copy violation" in the [make-testdata](https://github.com/unicode-org/icu4x/blob/main/provider/source/src/tests/make_testdata.rs) test
  - [ ] Constructors should avoid allocating memory in the common case
  - [ ] Opaque blobs of data should be avoided if possible (instead use VarZeroVec, ZeroMap, etc.)
  - [ ] Data structs should not be panicky to load/deserialize and conform to [data_safety.md](https://github.com/unicode-org/icu4x/blob/main/documents/design/data_safety.md)
  - [ ] If any data structs use a large or unbounded number of data marker attributes, they are implemented in a way that reduces stack space, file size, and construction time, such as by having only a single variable-length field
- [ ] The component should be fully integrated with ICU4X tooling
  - [ ] There should be an overview Criterion benchmark
  - [ ] There should be individual Criterion benchmarks for interesting or performance critical code paths
  - [ ] There should be at least one example plumbed with the icu_benchmark_macros
  - [ ] The component should be fully covered by FFI with no unjustified suppressions nor entries in missing_apis.txt
- [ ] The component should encourage i18n best practices
  - [ ] The component should produce correct results in all locales as generated by icu4x-datagen
  - [ ] Where applicable, the component should be consistent with ECMA-402 and UTS#35
  - [ ] Any gaps in i18n quality should be fixed, or, if that is not possible, they should have tracking issues and a concrete, resourced path forward. The intent is to not ship components with known i18n correctness problems and no plan to fix them in an upcoming release
  - [ ] The API design should receive sign-off from a non-ICU4X i18n expert such as Markus Scherer
- [ ] Make sure the graduation PR has a comprehensive changelog entry (see [changelog.md](changelog.md))