Page MenuHomePhabricator

Efl Api Stabilization Workflow
Updated 1,310 Days AgoPublic


EFL's API is currently transitioning from the Legacy version to the Unified version.
Legacy is mostly a C-only API, evolved over several years, mixing multiple libraries.
The Unified API is currently under development, it offers a single namespace and allows accessing it from languages other than C (like C#, for example).

Unified API stabilization

Most of the Unified API is defined in EO files. Initially, ALL classes were marked with a @beta tag, meaning that that class was subject to change and application writers should NOT use it.
All classes are now being carefully examined by multiple reviewers, sometimes modified, and when there is consensus that the class is good enough, the @beta tag is removed and the class is declared stable. Only then it can be used by application writers.

Stabilization infrastructure

The stabilization process is controlled from Phabricator using the following two resources.

- Tracking tasks

Each beta class has an associated tracking task. For example, T7897 tracks the stabilization process of class Efl.Ui.Spin, with children tasks for all its dependencies. In this way, it is easy to see if a class is ready to be declared stable, because all its dependencies must be stable first.
Task T7510 groups all tracking tasks (it's a big list).

- API project board

These tracking tasks have an efl: api tag, so they show in the API project board.
This board allows grouping the evaluated classes into categories:

  • Needs experts: These tasks are on hold until an expert in that field can look at them.
  • Backlog: These tasks are pending evaluation.
  • Evaluating: These tasks are currently being evaluated. There should be active discussions in their comments.
  • Trivial: These tasks are pending evaluation, but should be extremely easy to evaluate.
  • Stabilized: These tasks have been declared stable.

Stabilization workflow

These are the steps to follow when changing a class, method or type. Bear in mind that things not marked as @beta are stable, so changing them is an API break and is forbidden.

Proposing changes

  1. Choose a class from the Evaluating column in the efl: api project board (If there is no class in the Evaluating column that you'd like to work on, you can move tasks from the Backlog or Trivial columns into the Evaluating columns.)

    The class description should list all its properties, methods and events. These are the things that needs to be analyzed.
NOTE: There is no need to take ownership of the task. We all comment on the tasks, so there is not really an "owner".
  1. Add comments to the task with your thoughts. This should start a discussion with other developers. Everything can be discussed, for example:
    • Are the names clear enough? Or are they confusing for newcomers?
    • Is this API future-proof enough? Maybe there is something we would like to cover in the future that this API will not allow, unless we modify it a bit. The Legacy API still supports many cases which the Unified API does not, for example.
    • Can this API be simplified? Maybe different classes can be merged? Maybe some type can be made generic so multiple classes can use it, instead of having each class define it for their private use?
    • Is this API legacy-locked? The Unified API evolved from the Legacy API and in some places there are still references to legacy classes or names. This should be removed.
  1. Produce Action Items. When there is a general consensus that a change is needed, an Action Item is added to the task description using check boxes [ ], for example:
    • Class should be renamed to Efl.Ui.SpinButton.

Applying changes

  1. Say that you're going to be working on an Action Item. Before starting, add a comment to the task saying that you will be working on an Action Item and put your name next to the Action Item in the task description. In this way we make sure we do not duplicate work.
  1. Submit a patch for each Action Item. The patch should reference the tracking task (For example, Ref T7897).

    If the patch is accepted and it lands in master, you can tick off the Action Item from the task description with an [X]. For example:
    • Class should be renamed to Efl.Ui.SpinButton.
  1. Move the task to the Stabilized column once all Action Items have been executed and there is consensus among the developers that the class is ready.
Last Author
Last Edited
Jul 9 2019, 1:23 AM
woohyun, cedric, zmike, bu5hm4n