Defining a process to migrate experimental APIs to stable

[Daniel Hosseinian]

Hi all,

The CONTRIBUTING doc says: 

NOTE, the process of migrating from experimental to stable isn’t well defined at this point. We have experimental APIs which have been that way for multiple years. We should work to better define how this transition happens.

I'm starting this email thread as a forum to propose potential processes.

My proposal is the following:

1) An experimental API is eligible to become stable one year after its initial introduction.

2) The one year period should probably be tracked on Monorail (crbug.com/pdfium).

3) When one year has passed, anybody may propose the transition to stable on this mailing list.

4) One week will be given as an opportunity for objections.

5) Any major changes to the API will add 6 months to the waiting period from the date of the change and a transition to stable would need to be reproposed after that period has passed.

Thanks,

Daniel

--

Daniel Hosseinian Software Engineer dh...@google.com +1 424-341-4575

[K. Moon]

I don't think a purely time-based scheme is the right approach; it should be more of a positive decision as to whether experimental APIs should be promoted to stable. There should be evidence for doing so, rather than simply a lack of evidence of harm.

New APIs perhaps should come with some sort of proposal that includes conditions that would make them eligible for promotion to stable APIs. Then we can review those after a suitable bake time. (6 months?) We probably need to document some sort of holistic API design philosophy as well.

Perhaps it'd be good to start by enumerating what value we want to get from distinguishing between experimental and stable APIs in the first place?

--
You received this message because you are subscribed to the Google Groups "pdfium" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pdfium+un...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/pdfium/CAKUjZ-4MbLeDP0ZWoBY7dKy_L9-W9y8xdVP-kwU%2BTgYK9YpMFg%40mail.gmail.com.

[Ankit Kumar]

Experimental APIs: Subject to change without any notice.

Stable APIs: Sort of set in stone around what this would do. If we want to change it then we notify developers that we are changing the writing on the stone.

For an API to transition from Experimental to Stable, we need to ensure that the API is now set in stone and will not change. For me, this means a proposal for transition should make a case as to why this API is the final version and no changes are required to it.

If an embedder is only using stable APIs then they should be able to roll pdfium_revision without even thinking about what changed in pdfium most of the times. That kind of free from worry is what we are providing by marking an API as experimental or stable. 

Additionally I agree that there needs to be a minimum time for an API to be eligible to transition from experimental to stable.

I seem to be re-iterating the same content as Kahmy mostly so perhaps it would have been easier to just do a +1 to Kahmy's point.

[Daniel Hosseinian]

Ankit's distinction between stable and experimental is pretty spot on. To add on to what was already said, any "changes" to a stable API would have to be in the form of a new experimental API and an eventual deprecation of the old API. 

If we are going to make a formal proposal a prerequisite to landing an API, we also need to establish a group of contributors who will review and approve those proposals. So far, any PDFium committer has been able to approve an experimental API without a discussion among the wider community.

We should also provide some sort of proposal template.

To view this discussion on the web visit https://groups.google.com/d/msgid/pdfium/fd5ac7a1-e478-4f43-9457-f41db37bbeb1n%40googlegroups.com.

[K. Moon]

I like Ankit's specific ideas (I just had some vague criteria I wanted to see), as well as Daniel's ideas about process. Perhaps the next step is to start drafting up a policy doc? I don't think it would have to be more than 1-2 pages.

To view this discussion on the web visit https://groups.google.com/d/msgid/pdfium/CAKUjZ-5yDTkMYF0Ugu%3D_YOtb4OT0gBBQtFL542%3DXM8EKpt4a4Q%40mail.gmail.com.

[Daniel Hosseinian]

Sounds good to me. 

I'll start drafting a doc, perhaps with the help of some of my colleagues on the Chrome team. No promises on when it will be ready though.

When the first draft is ready, we'll send it over to this list to get wider input from this group before setting anything in stone.

More ideas are welcome on this thread until then!

[Miklos Vajna]

Hi,

On Fri, Jan 29, 2021 at 07:54:40PM -0800, 'Daniel Hosseinian' via pdfium <pdf...@googlegroups.com> wrote:
> More ideas are welcome on this thread until then!

I think taking time into account is a good idea: if something is
experimental and no problems happened with it for years, then it's
likely a good candidate to be a stable API, as happened in
<https://pdfium-review.googlesource.com/c/pdfium/+/77650>.

The other factor we may want to consider is if there are known clients
of that API. If an experimental API is known to be used by
Android, offline conversion tooling, etc -- then it would make more
sense to graduate that to stable; compared to an API which is not really
used by anybody.

Regards,

Miklos

[Lei Zhang]

To carry forward the discussion, I put up a draft for the API promotion process as a CL. Feel free to review, like with any other CL. https://pdfium-review.googlesource.com/82190

To view this discussion on the web visit https://groups.google.com/d/msgid/pdfium/CAKUjZ-5ojXQ6ak6afQESB0fjFyWV--kjUY3dXtrDKrEbcZF6HA%40mail.gmail.com.