Initial draft policy on supported platforms and dependencies
Here's a draft of a policy to say about what we support, and what we don't. It's quite incomplete at the moment, but I hope it can be a starting point for us to discuss and improve.
Closes #379 (closed)
Merge request reports
Activity
assigned to @nickm
requested review from @Diziet
This is definitely in the right direction.
I still have a bit of a problem with the word "supported", which is used many times without definition. That word can mean different things to different people. Indeed in this document it is even used with different meanings in different places.
Questions that this document needs to answer are:
- What do we advise users and embedders to do
- What steps do we take to ensure quality/workingness/whatever
- What patches will we take
- What advisories will we issue
(1) and (2) are addressed very well. (3) and (4) partially.
As a thought experiment, I read it trying to replace "support" with some longer phrase each time it appeared. I don't think the result would be very nice.
Perhaps instead we should take the approach of defining "levels" of support. I think this document offers the following levels (if they only need to address points (1) and (2)):
- unsupported: we will generally reject, without substantive review, patches
- best effort: we will review patches and accept them on their merits, but we won't do any systematic verification or testing
- supported: additionally, we will do systematic verification and testing
- security-supported: additionally, we will issue an advisory if we become aware of a severe enough vulnerability
added 1 commit
- a42a6467 - SupportPolicy: Add tiers, clarify what "support" means.
9 9 promise. For now, we'll deviate from these policies whenever it we think it 10 10 makes sense, and we'll amend from time to time without notice. 11 11 12 ## Elements of support 13 14 For this document, we define the following support tiers. 15 16 If a configuration is **unsupported**: -
I would move this to a separate sub-heading ("
### Unsupported configurations") and mention all the unsupported stuff in that heading. e.g.### Unsupported configurations We don't support proprietary operating systems, [etc]. This means that: * We do not typically accept patches related to these configurations [etc](The rationale here is "putting this front-and-center adds to the list of supported configurations you have to keep in your head")
9 9 promise. For now, we'll deviate from these policies whenever it we think it 10 10 makes sense, and we'll amend from time to time without notice. 11 11 12 ## Elements of support 13 14 For this document, we define the following support tiers. 15 16 If a configuration is **unsupported**: 17 18 * We do not typically accept patches related to the configuration. 19 * We do not issue security advisories related to the configuration. 20 * We close tickets related to the configuration as wont-fix. 21 22 If a configuration is **community-supported**: -
Maybe we could give these numbers, like Rust's platform support; for example, this might be "Tier 1". That lets you sort levels of support more intuitively, maybe (?)
Hmm. I'd like to make this as clear as possible, but I'm not sure that the numbers are more clear than the words, especially since we reference them elsewhere in the document out of order. Remembering the distinction between tier 3 and tier 4 seems harder than remembering the distinction between maintained and community-supported when we see those terms elsewhere.
Maybe for clarity it would be better to rearrange the document so that everythign related to one tier is in the same place. In other words it would go something like:
- Tier 1 (tested)
- What 'tested' means?
- 'tested' operating systems
- 'tested' CPU architectures
- 'tested' dependencies
- 'tested' rust versions
- Tier 2 (target)
- What 'target' means
- 'target' operating systems
- ...
- ...
- Supported versions of Arti
- API compatibility
- Security advisories
- Tier 1 (tested)
28 29 Additionally, if configuration is **maintained**: 30 31 * We commit not to knowingly make releases that break the 32 configuration. 33 * If we learn that the configuration is broken, we prioritize fixing 34 it. 35 * We write and announce security advisories if we learn about security 36 issues in the configuration. 37 38 39 Additionally, if configuration is a **target**: 40 41 * It is a higher priority for us than other **maintained** 42 configurations. 43 * We'd like to make it a **tested** configuration, if we have the 44 resources. We intend to add more testing to it until it can become 45 **tested**. 46 47 Additionally, if a configuration is **tested**: 48 49 * We have automated systems to make sure that the configuration 50 builds and runs tests correctly. 51 * We have one or more team members who "dogfood" the configuration, 52 using it ourselves to get rapid notifications about usability 53 problems. 54 55 (Note that no broad configuration can be fully **tested** in all of its 56 permutations. For example, our automated tests can only be run on a 57 limited set of the number of Linux distributions and versions, when in 58 fact there are vast numbers of possible Linux installations whose 59 variations might affect our behavior.) 23 We only support modern versions of these operating systems. (If the 24 upstream providers of the operating system no longer support it, neither 25 do we.) 72 We only support modern versions of these operating systems. If the 73 upstream providers of the operating system no longer provides security 74 patches for it, it is **unsupported**. Sufficiently old versions may 75 also be **maintained** or **community-supported**, depending on their 76 age and the difficulty of working with them. 26 77 27 We currently have automated builds and tests on Linux only. On OSX and 28 Windows, we have automated builds, but the tests are not (yet) run. In the 29 long run, we aim to have automated builds and testing for all of our priority 78 We currently have automated tests on Linux only. On OSX and Windows, we 79 have automated builds, but the tests are not (yet) run. In the long 80 run, we aim to have automated builds and testing for all of our these 30 81 platforms. -
I think this new version does a good job of specifying things in more detail, which users arguably want. However, I think it probably goes a smidge too far, to the point that while reading it I kind of got a bit confused having to hold 5 tier levels in my head (kind of like a legal document with a big page of Capitalized Definitions at the start which you have to remember).
I've left a few non-blocking comments on how I think it could be improved; please feel free to ignore any or all of them and merge at your leisure (after @Diziet weighs in too, that is)
-
I've tried to note what my rationales were for the parts I put in, and noted a possible alternative organization for some part of the document.
@Diziet what do you think about the reorganization I suggested?
added 1 commit