Proposal: Tiers of support and faster progress in the future

[complexspaces]

Hello everyone,

Firstly, I would like to make something clear upfront: The issue's current title should indicate it but this is not a proposal for maintainership transfer, like #26 was. Then, just in case it comes up: everything here is my own and not endorsed by or representative of my current employer.

Several people may have noticed that my activity reviewing PRs and triaging issues here has not been consistent over the last ~year or so. Firstly, I would like to issue an apology to everyone who has tried to contribute or submit issues in good faith. While open source maintainers do not have an obligation to provide free services to anyone, I personally consider my own lack of feedback or updates to be unprofessional (this is solely for myself, I do not think this of any other project or maintainer).

Today's standards for contributions and maintenance

The primary reason for the current state of things has been my bar for quality and verification of functionality: I really like to ensure that anything I merge into main if functional like downstream users expect and that I'm able to maintain the code added through various platform changes and niche edge cases. This is because, at the end of the day, those who write code in PRs are not expected to maintain it going forward, that falls onto the repository and crate owner in the standard OSS contract. That's just me today and everyone only has so much time and expertise 😄.

When prospective contributors propose new changes or large behavior shifts that may break in subtle ways or be difficult to keep smoothly-operating in the future I often find it hard to assess the long term impact of accepting the changes even if they work perfect at the time of review. I want arboard to be a good citizen on the host platform, not a "hack", and integrate into all applications type as much as feasible. In my experience, this can be challenging at times.

Clear examples of this are requests to support new platforms like Android or WASM in the browser. I'm well aware of these platform's quirks and long-term shifting requirements from my participation in clipboard-related topics internally at 1Password, where we have to ship a functional clipboard for 9 targets (5 OSes and 3 browsers). This hesitation is what what has surfaced as silence. As an example: Will I have the time and energy to provide a timely fix if where arboard starts spamming users because the blessed approach to clipboard access on a mobile platform changed?

Availability

The second reason is quite widespread: time. As a transparency update, despite this crate being under the 1Password organization, its the same situation today as what was said here in 2022. I am not paid to work on this project as part of my job responsibilities and there are no longer other employees who help handle this crate. My employer has been generous enough, and continues, to let me spend some paid hours here and there keeping the lights on. But, almost all of the time spent on arboard comes from my personal life because I like it and want to provide valuable tools to the Rust ecosystem, have an excuse to do systems-level programming, learn new OS concepts, and interact with the Rust community.

As a short anecdote: This is the single biggest reason so many issues related to the Linux backends sit for long periods. It is, honestly, tiresome to work out where bugs may be coming from the exponential combination of windowing servers, compositors, and desktop-specific quirks (ex including a clipboard manager by default or not).¹

Moving Forward

Now, with the rationale for this and explanation of the past out of the way, I'd like to make things better moving forward. This is for several reasons:

1. I want to remove barriers that obstruct me from being active here so I can be more responsive and proactive.
2. I want to ensure contributors and users have a better experience.
3. I want to use (1) and (2) to further where arboard is usable and can provide value.
   3.1. My opinion is that fracturing support for abstractions over platform-specific functionality makes it hard for users to do what they actually care about.

To do this, I want to introduce (and am currently planning) two large scale policy updates:

Platform support tiers (1/2)

Introduction of an platform support (and for some targets, environment) tiers into arboard (inspired by what Rust itself does). The intent is that any functionality I can't make an upfront commitment to the absolute functionality or "optimal" behavior of will be marked with a level of corresponding support expectation. At this time I am not planning on introducing any Cargo feature flags to guard anything, unless something changes in a major way in the future where its shown that users need to opt-in for some reason.

My current design idea also has three tiers:

1. These platforms are fully supported:

   • Users can expect bugfixes and behavioral fixes following a normal issue reporting process.
   • Everything will, modulo bugs, run as intended on the host platforms.

2. These platforms are supported and I have interest in keeping them function:

   • Issues and behavioral problems will be triaged at minimum.
   • Fixes and any research required may be deprioritized in the event its not a massively widespread problem or conflicts arise.
   • Runtime behavior should work as intended in most cases, but quirks should be expected due to either ecosystem fragementation or OS requirements.

3. These platforms are interesting to support and, benefit downstream apps, but they are provided more as-is then usual:

   • Maintenance and bug fixes are unlikely. Those interested in using the target may need to contribute more.
   • They must compile in CI and must not cause problems for nor interfere with better supported targets.
   • SemVer is explicitly not guaranteed. These platforms may have either platform-specific API changes or non-backwards compatible internal behavior changes made without a new major release.
     • A minor version (4.x.0) will be used to communicate this though.
   • If a large change needs to be made cratewide and a solution for a tier 3 platform can't be found in a time-boxed manner, it may be stubbed out (with documentation) or in severe cases result in that backend being deprecated.

The initial use case for this will be moving Android and web browser (WASM) support into completion.

Here's what I believe the assignments would be day 1:

Platform	Tier	Rationale
Windows	1	N/A
macOS	1	N/A
Linux (X11)	1	Unlike Wayland, X11 provides "the kitchen sink" (and such flexibility benefits) to apps like macOS and Windows do. Secondarily, it is no longer receiving protocol updates, and to my knowledge, no compositors are actively changing their implementations. As such, there are less moving parts.
Linux (Wayland)	2	Wayland implementations have varying functionality, implementation details, and interpretation by the implementers of compositors. This is especially the case given arboard's dependence on optional Wayland extensions.
Android (Java)	2-3 (TBD)	Maintaining JNI interopt code is burdensome and Android has a history of huge clipboard changes in recent years. Additionally, there may be some things arboard can't do with library code alone and would require supporting code from the hosting app.
Android (Termux)	3	The number of users of Rust CLI apps on Android is small (AFAIK) and I don't have interest in tracking a 2nd platform implementation. It seems stable, so my hope is this one is uneventful despite being tier 3.
Web Browsers	2	Some browsers, like Safari, have different approaches to implementing web specifications with privacy implications that may cause some behavior to not work in all situations. Browser quirks like this are outside of arboard's scope and should be expected.
iOS (hypothetical)	2-3 (TBD)	It will depend how much it diverges from the macOS implementation

If bugs or limitations surface in features or backends in a tier that 2 or 3, users are still welcome (and encouraged!) to file issues. However, the implicit understanding is that any fixes or improvements from crate maintainers are absolutely best effort. Triage will attempt to communicate this too. I may also ping the author who originally contributed the feature/backend for assistance coming up with ideas/suggestions if they're still active on GitHub.

However, critically, this does not mean that contributors who merge code for these platforms are automatically opted-into being responsible for that code forever. Their interest and effort would be greatly appreciated like any PR is, but I have no intentions to force anyone to do anything. While maybe weird to some, my current belief is that this model is still a net improvement over requiring crates like egui to depend on a bunch of different clipboard crates if the authors of the code inside would be identical and keeps platform abstractions high-level and usable where possible. That also makes the odds of drop-in functionality "just working" well enough for many more people!

Finally, I would like to point out that the properties of tiers are theoretical and may not match how they are actually treated. Several of them may be just fine long term and not noteworthy to worry about. The most important takeaway is communication of, and establishing, minimum expectations and making maintainers more comfortable doing the job.

Issue reporting requirements and templates (2/2)

Currently there is no template or documented standard for issue report details. This is because I've hesitated imposing expectations or requirements. However, time has shown this doesn't scale past a point and arboard his that threshold years ago.

Independent of part 1, I intend to implement issue reporting guidelines and possibly take advantage of GitHub's structured issue construction forms to help enforce them. These are primarily to assist in triage and determining impact:

• Host OS the crate is being used on
• Relevant sub-component of the host OS (such as the version of macOS or Windows, X11 or Wayland, Linux compositor/display server version, etc)
• Reproduction snippet and, if source is not available, context how the clipboard is being used
• Extra details that may be helpful like errors, logs, or data the clipboard was trying to handle.

Wrapping Up

With everything here in place, it will become significantly easier for me to review code and handle large-scale contributions. There's even a reasonable likelihood I still work on improvements and bugs for "unstable" platforms but removing the (even self-perceived) pressure of needing to do so is what's important here. Then, with a pinch of luck, arboard goes back to being fun and a-good-time to maintain and users get what they need faster.

cc @ArturKovacs, as you're still part of the project. Your feedback + past experiences with arboard would be valuable to hear.

Footnotes

1. This only increases in difficulty when many bug reports don't contain reproduction environment information, which often leaves it to guess work (and, like mentioned before, that often won't meet my standards). ↩