tree: 4ae272bf091598c56be50bc1c54ca79e080e1a2a [path history] [tgz]
  1. OWNERS
  2. README.md
  3. _toc.yaml
  4. ftp-001.md
  5. ftp-002.md
  6. ftp-003.md
  7. ftp-004.md
  8. ftp-005.md
  9. ftp-006.md
  10. ftp-007.md
  11. ftp-008.md
  12. ftp-009.md
  13. ftp-010.md
  14. ftp-012.md
  15. ftp-013.md
  16. ftp-014.md
  17. ftp-015.md
  18. ftp-016.md
  19. ftp-020.md
  20. ftp-021.md
  21. ftp-023.md
  22. ftp-024.md
  23. ftp-025.md
  24. ftp-026-figure1.png
  25. ftp-026-figure2.png
  26. ftp-026-figure3.png
  27. ftp-026-figure4.png
  28. ftp-026.md
  29. ftp-027.md
  30. ftp-029.md
  31. ftp-030-figure1.png
  32. ftp-030.md
  33. ftp-032-figure1.png
  34. ftp-032.md
  35. ftp-033.md
  36. ftp-035.md
  37. ftp-036.md
  38. ftp-037-transaction-header.png
  39. ftp-037.md
  40. ftp-040.md
  41. ftp-041.md
  42. ftp-042.md
  43. ftp-043.md
  44. ftp-044.md
  45. ftp-045.md
  46. ftp-048.md
  47. ftp-049.md
  48. ftp-054.md
  49. ftp.template_md
docs/development/languages/fidl/reference/ftp/README.md

FIDL language tuning proposals

Note: Documents are sorted by date reviewed.

Accepted proposals

FTPSubmittedReviewedTitle
FTP-0012018-07-172018-08-01FTP process
FTP-0022018-07-172018-08-03Type aliases with “using” keyword
FTP-0092018-07-312018-08-20Documentation comments
FTP-0122018-08-302018-09-11Empty structs
FTP-0072018-07-272018-09-20Tables
FTP-0032018-07-172018-09-27Clarification: Default Values for Struct Members
FTP-0082018-07-192018-10-04Epitaphs
FTP-0132018-09-072018-10-11Introduce a [Deprecated] Attribute
FTP-0152018-09-202018-10-11Extensible Unions
FTP-0212018-10-312018-11-01Soft Transitions for Methods Add / Remove
FTP-0202018-10-262018-11-29Interface Ordinal Hashing
FTP-0142018-09-182018-12-06Error Handling
FTP-0232018-12-102019-01-09Compositional Model for Protocols
FTP-0062018-07-202019-01-14Programmer Advisory Explicit Defaults
FTP-0252019-01-092019-01-24Bit Flags — Just a Little Bit
FTP-0302019-01-302019-01-30FIDL is little endian
FTP-0272019-01-192019-02-04You only pay for what you use
FTP-0322019-02-062019-02-21Efficient Envelopes: Turning Envelopes into Postcards
FTP-0292019-02-142019-02-28Increasing Method Ordinals
FTP-0332019-02-072019-03-07Handling of Unknown Fields & Strictness
FTP-0042018-07-192019-03-14Safer Structs for C++
FTP-0372019-03-072019-03-14Transactional Message Header v3
FTP-0242019-04-022019-04-11Mandatory Source Compatibility
FTP-0412019-04-082019-04-23Support for Unifying Services and Devices
FTP-0432019-05-062019-05-30Documentation Comment Format — Mark me up, mark me down
FTP-0482019-08-252019-09-26Explicit Union Ordinals
FTP-0542019-11-212019-12-12Parameter Attributes — A Chance to Write Self Documenting APIs
FTP-0492019-11-202019-12-19FIDL Tuning Process Evolution

Rejected proposals

FTPSubmittedReviewedTitle
FTP-0052018-07-192018-09-11Method Impossible
FTP-0102018-07-312018-10-04[OrdinalRange], where the deer and the antelope roam
FTP-0162018-09-272018-10-25No Optional Strings or Vectors
FTP-0262019-01-192019-02-04Envelopes Everywhere
FTP-0352019-02-28withdrawnAutomatic Flow Tracing
FTP-0362019-03-072019-03-14Update to Struct Declarations
FTP-0422019-04-012019-04-01Non Nullable Types — Poisson d'Avril
FTP-0402019-04-072019-04-18Identifier Uniqueness — SnowFlake vs SNOW_FLAKE
FTP-0452018-12-262019-05-29Zero-Size Empty Structs: ∞% more efficient

Process

The FIDL Tuning Proposal (FTP) process is designed to provide a uniform and recorded path for making changes to the FIDL language, bindings, and tools.

Criteria for requiring an FTP

A change MUST go through the FTP process when either:

  1. The solution space is large, i.e. the change is one of many possibly good other solutions and there is a difficult design tradeoff to make;

  2. The change has a large impact, i.e. The change modifies the behavior of FIDL in a substantial way such that it may introduce risk to many-or-all users of FIDL;

  3. The change has a large scope, i.e. The change touches enough pieces of FIDL such that careful attention is required to determine whether it may or may not have a large impact.

For instance, changes to the following areas will likely require an FTP:

  • FIDL governance
  • Design principles
  • Language grammar
  • Type system
  • Protocol semantics
  • Wire format
  • Bindings specification

Additional details are provided in FTP-049: FIDL Tuning Process Evolution.

Design

An FTP (FIDL Tuning Proposal) goes through several stages. These stages correspond to the Status: field of the heading of the template.

NB: The template is currently Google-internal.

Draft

One or more people get excited about a change! They make a copy of the tuning template, and start writing and designing. The proposal should address each of the section headings in the template, even if it is only to say “Not Applicable”.

At this stage they may start soliciting feedback on the draft from impacted parties.

Comment

At this stage, the FTP is formally circulated for commentary to the Fuchsia engineering organization. The authors of the proposal should solicit feedback from those especially likely to be impacted by the proposal.

For now, proposals should be left open for comment for at least one week, subject to reviewer discretion. It may be reasonable to be shorter for less controversial FTPs, and longer to wait for feedback from a particular person or group to come in.

Anyone may make a blocking comment on an FTP. Blocking comments do not prevent a particular accept-or-reject outcome from the review process, but reviewers are required to acknowledge the feedback given in the comment as part of the final FTP.

Withdrawing

Withdrawn FTPs are valuable records of engineering ideation. When an author withdraws their FTP, the withdrawal rationale must be added to the FTP. The FTP will then be copied to the public record of all FTPs for posterity.

The withdrawal rationale is written by the FTP author, possibly in conjunction with members of the Fuchsia FIDL team.

The rationale should be actionable in the following two ways.

What did the author learn through the FTP process which would have led them to propose an alternative design?

What are alternatives to the withdrawn FTP which are promising?

Review

At this point the FTP, along with all outstanding commentary, is reviewed.

The proposal is reviewed by members of the Fuchsia FIDL team (defined by an OWNERS file in the fuchsia.git repository [Location TBD], and unofficially known as luthiers), and anyone they see fit to include or to delegate to in the process. For example, they may include a particular language expert when making a decision about that language's bindings. If necessary, controversial decisions can be escalated like any other technical decision in Fuchsia.

Most commonly, the review is conducted during one or multiple in-person meetings ‘The FTP review meeting’. The review can also occur using asynchronous communication if appropriate).

The FTP review meeting starts by the author(s) presenting their design. The facilitator will then work through the comments in the FTP, asking people who left comments in the doc to present their feedback.

The facilitator and presenter are ideally different people. The goal of the facilitator is to ensure that all aspects of the design are addressed, and to keep the meeting flowing. Ideally, the facilitator does not have a particular stake in the outcome to avoid the perception of bias, and the presenter implicitly has a stake in the design they're presenting.

We don't necessarily need to come to closure on every piece of feedback during the meeting or discuss every last comment (e.g., if there are a large number of comments or several comments are getting at the same underlying issue). Instead, the facilitator should optimize for giving the presenter a broad range of feedback rather than driving each point of debate to a conclusion. Pending open questions may be resolved in further review sessions, or during Decision making.

Decision making

Within five (5) business days, members of the Fuchsia FIDL team (defined by //docs/development/languages/fidl/reference/ftp/OWNERS file), with the ultimate decision maker being the Fuchsia FIDL team lead, decide on the outcome of the review.

The decision can ultimately have three outcomes.

First, there may be outstanding questions or feedback required to make a decision. In this case the FTP is moved back to the Comment stage.

Second, the proposal may be Rejected, with reviewers providing a rationale as to why.

Third, it may be Accepted.

Typically, the venue for decision making will take the form of a meeting. It may also be an email thread, or happen during a review meeting.

Rejected

Rejected FTPs are valuable records of engineering decisions. When rejected, the rationale for rejected should be added to the FTP. The FTP will then be copied to the public record of all FTPs for posterity.

The given rationale should be actionable in the following two senses.

First, what would have to change about the world to have accepted this proposal?

Second, the rationale should address any blocking comments raised during the Comment period.

Accepted

Accepted FTPs will also have a rationale section appended to them after review, and will receive a tracking bug.

The same constraints apply to the acceptance rationale as the rejection rationale. In particular, any blocking comments need to be addressed.

Then it's off to the races to implement the change.

Implemented

At this stage, the proposal is landed. All the code has been changed. The tutorial has been updated. The bug is marked done. FIDL is in a more perfect tuning.

The final step of the process is landing a markdown-ified version of the FTP into the Fuchsia tree. This applies whether or not the proposal was accepted, as being able to point at already considered but rejected proposal is a substantial part of the value of this process.