Skip to content

Latest commit

 

History

History
51 lines (49 loc) · 5.15 KB

graduation.md

File metadata and controls

51 lines (49 loc) · 5.15 KB

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
  • Add the new features to the changelog in the "Unreleased" section