The new EFL Unified API has been in the cooking for several years now, with a significant effort to finish it in the past 3 years (prior to 2020). With such an extended development time it was important to establish a set of rules to be as efficient as possible while producing a robust and enjoyable API.
Keep in mind that once a method is declared stable it cannot be changed without breaking compatibility: a minute spent designing the API can save years of dragging around inefficient, misleading, or just plain ugly legacy methods.
The process described here deals with the API design, this is, choosing the best signature (name, parameters, ...) for each EFL entry point. The goal is to have an API as homogeneous and easy to use as possible.
Implementation details or whether or not a new feature is appropriate is outside the scope of this process.
This document describes the rules we followed so far. They are in no way compulsory, but they have been extremely helpful in the past.
In EFL's Unified API all API is described in .eo files. All the talk in this document about landing API changes refers to modifying .eo files and any associated .c file.
The process starts with someone proposing a new class, or just a symbol name or method signature (This traditionally happened without discussion when someone landed the changes directly on master tagged as BETA).
Then public discussion follows, changes can be made if necessary and when there are no objections the new API is landed and considered stable.
This happens totally outside the git repository, with Phab tasks as described below. But tentative API can also be landed using the @beta Eolian tag to ease collaboration. Stabilization then simply consists in landing a patch that removes the @beta tag.
- Create a new Phabricator task using the proposed symbol name as title.
- Tasks in the efl: api board can then be reviewed by everybody in an orderly manner. To help prioritize which tasks should be reviewed first, the board is divided into 5 columns:
- Needs experts: The task is sort of "frozen" until an expert in the field chimes in and gives their opinion.
- Backlog: The task is not scheduled for discussion yet.
- Evaluating: The task is open for discussion now. Feel free to make comments and propose changes.
- Trivial: The task is open for discussion, but not much of it is expected. This is an indicator of "easy" tasks which you can take a quick look at if you don't have much time.
- Stabilized: Discussion has ended and the proposed API is considered stable. Code can be landed once a task reaches this stage and then the task can be closed.
Tasks are moved from column to column by consensus. Typically, an some sort of discussion decides which tasks should be processed next (moved from Backlog to Evaluating) and the discussion thread on a particular task decides when that task is good enough to move to Stabilized.
This is an unordered list of topics that need to be addressed when checking if an API proposal is fit for stabilization. This list is in no way exhaustive.
- Aim at reusing API like you would reuse code: Abstract portions of a class to an interface if you detect functionality overlap with other classes.
- Is this class or method consistent with similar usages in other parts of the API? Consistency helps learning the API.
- Favor properties over methods: A property color translates to other languages better than separate color_set and color_get methods (even for read-only properties).
- Favor iterators over specialized containers like list, array or hash. In this way the API does not change much and it frees the implementation to use any container it desires in the future.
- Avoid write-only properties: Use a method instead.
- Typos are absolutely forbidden. Use a spell checker.
- The American English spelling is preferred.
- Property names should be nouns (like position, size or color).
- Method names should end with a verb (like widget_sub_object_add or theme_apply).
- Event names should use a verb in past tense (like position,changed, or size,changed).
- Is the name clear and unambiguous? Things like update are overused and do not convey much information. Do not be afraid of add more words, or use longer words, to better express the purpose of a method.
- Has this name been used elsewhere with a different meaning? If so, a different name has to be chosen (Thesaurus usage is highly recommended).
- Conversely, has a different name been used elsewhere with the same meaning? If so, try to use the same name as already used. Consistency, consistency, consistency...