Policy for adding platform support

[carllerche]

Adding support for a new platform requires non trivial work to implement and maintain on an ongoing basis. I personally do not have the time to maintain the growing number of platforms.

Given this, I propose the following process to add support for a new platform:

1. At least one person commits to provide ongoing platform maintainership and be responsive in a reasonably timely fashion. This includes bug fixes as well as development work required to track Mio's APIs and features.

2. An initial PR is submitted that does not modify any portion of Mio that is not directly related to adding platform support. If any changes to Mio that impact other platforms must be made, then they should be submitted as separate PRs to be evaluated independently. All unit tests must demonstrably run successfully and the platform must be included somehow in the CI run.

3. The platform support becomes experimental during an incubation period. The duration of this period can be determined over time. Experimental support means that a) users must opt into it using an unstable_[platform] feature flag and b) support for the platform may be removed during the incubation period if maintenance lags or there is insufficient usage of the platform.

4. At some point in the future, the platform graduates to long term support. At this point, any changes to Mio must include support for this platform.

Thoughts?

[asomers]

Number 1 is important, but often overlooked. People thing that "if it's working on X and it's got CI for X, then X is supported", but forget that there also needs to be a commitment to fix platform X whenever it breaks. I would suggest a tiered platform list like this:

• Tier 1: It works, it's got CI, and it's got a maintainer. Mio will commit not to make a release if this platform is broken. Mio won't drop this platform back to Tier 2 or lower without a major version bump.

• Tier 2: It works, it's got CI, it's got a maintainer, but it's still experimental. Mio might decide to drop this platform in the future with little warning.

• Tier 3: "Patches welcome". Releases will not be held back for this platform's sake. Nor will pull requests. Support is contingent on community contributions. By default, all platforms start here.

• Unsupported. Pull requests for these platforms are not welcome, because demand for them is low and support for them forces too many compromises on mio's platform-independent code. An OS with a non-Berkeley-sockets-based network API might fall into this category.

I'm leery of requiring feature flags to opt into tiers 2+. I worry that this might not work in all build environments. For example, if mio is consumed by a platform-independent library "mio-foo" that doesn't know about the unstable flags, and "mio-foo" is consumed by application "fooserver", will a user on a tier 2 platform be able to install fooserver with "cargo install"? I don't see a way to do that using the cargo command line. It's probably unnecessary anyway. Users of minority platforms are used to the idea that stuff doesn't always work out of the box.

[carllerche]

I thought feature flags could be nice to make the unsupported nature explicit, but I see your point.

I'm hesitant about having a "patches welcome" level of support as that takes non trivial amounts of time from the primary maintainers. Every PR submitted must be carefully reviewed to ensure no accidental breaking change is introduced.

[asomers]

It certainly does take some time. But without a "patches welcome" stage, how will anything ever reach Tier 2? It's got to start somewhere.

[carllerche]

@asomers My main concern is that I need a way to remove the platform support of it stagnates. That strategy needs to be communicated somehow. I am trying to avoid becoming the default maintainer of a platform if people disappear. Thoughts?

[asomers]

How about requiring every tier 1 and 2 platform to have at least one explicit maintainer. I all maintainers of a tier 2 platform quit or go AWOL, then the platform can be demoted to tier 3 at any time. If all maintainers of a tier 1 platform quit or go awol, then you're stuck maintaining it yourself until the next major release. Of course, rules about major releases don't apply before 1.0, as usual.

[jD91mZM2]

@asomers' suggestions look really good. I'm not sure about the "patches welcome" tier personally as it's more work for a maintainer to keep fixing their platform being broken unexpectedly from every single PR than it is for a contributor to not break the platform

[carllerche]

Here are more thoughts:

• As much OS specific code lives in a separate crate maintained by the platform expert. This will allow them to manage fixes / iterate without blocking on mio devs. This crate will provide an interface similar to mio itself and mio will then use this crate to provide support for the platform in question. For example, windows specific code will be moved to wepoll.

• Platform specific code that must be in mio is kept in dedicated files as much as possible. This should help avoid the mess of confusing cfg flags.

cc @Thomasdezeeuw

[Thomasdezeeuw]

@carllerche Splitting OS specific code into different crates sounds good. But this only solves the code side of things, not the support/maintainence. We still need people with the proper knowledge and time available to maintain the code, whether it lives inside mio or in another crate.

[carllerche]

@Thomasdezeeuw Correct. The above policy would still apply regarding maintainership.

[Thomasdezeeuw]

Not sure were to put this, so I'm putting it here. In regards to what OS versions to support, @carllerche and I decide on as best effort support of RHEL 6 (kernel 2.6.32-754).

[Thomasdezeeuw]

The original idea of the policy sounded good. But the reality turned out different.

The reality is that I maintain most of Mio myself and ping people that are knowledgeable about platforms specific code (usually based on past contributions).

Based on the above I'm going to close this as, even if we would write such a policy, enforcing it at the moment is not feasible.