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:
    • [ ] The crate should have a complete library header as shown in 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)
    • [ ] If there is a Borrowed type, then compiled data constructors like Foo::new() must return FooBorrowed (#5440)
    • [ ] Options bag enum fields should consistently be wrapped in an Option, ideally with a better-named default/“auto” variant (#5488)
  • [ ] The data structs should fully follow ZeroVec style
    • [ ] Deserialization should not have a “zero-copy violation” in the make-testdata 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
    • [ ] 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)