From 276449cccdbe9ba7b086509ca3d845df366c5b47 Mon Sep 17 00:00:00 2001 From: Matt Holt Date: Fri, 29 Mar 2019 22:49:32 -0600 Subject: [PATCH] Caddy 1.0 compatibility contract --- Compatibility-Guarantee.md | 35 +++++++++++++++++++++++++++++++++++ Compatibility-Notice.md | 7 ------- 2 files changed, 35 insertions(+), 7 deletions(-) create mode 100644 Compatibility-Guarantee.md delete mode 100644 Compatibility-Notice.md diff --git a/Compatibility-Guarantee.md b/Compatibility-Guarantee.md new file mode 100644 index 0000000..58fff44 --- /dev/null +++ b/Compatibility-Guarantee.md @@ -0,0 +1,35 @@ +Caddy 1 must remain backwards-compatible. This document defines and describes what breaking changes are, and the expectation users can have regarding compatibility on the v1 tree. + +- It is expected that a v1 Caddy instance may be upgraded to any newer v1 Caddy instance without requiring changes to its configuration, system, or environment to maintain the current, desired behavior. +- A breaking change is one which violates this expectation. + +This compatibility contract applies to: + +- Caddy environment variables and CLI flags +- Caddyfile configurations +- Caddy's plugin API + +We will try to avoid breaking changes, but in practice, compatibility cannot be guaranteed in all cases. The following scenarios are exempt from the compatibility contract, and we reserve the right to make breaking changes without remediation for: + +- **Security.** Confirmed vulnerabilities in which the most practical fix is a breaking change. +- **Undocumented behavior.** That which is not documented or which is documented incorrectly is not subject to compatibility promises. +- **Documentation errors.** If documentation is found to be incomplete, ambiguous, or straying from intended behavior, changes to the documentation may be warranted to ensure its consistency with the software. Such changes could affect the legality of related configuration, etc. +- **Bugs.** Instances which rely on buggy behavior may break when bugs are fixed. +- **3rd-party plugins.** We cannot guarantee the compatibility of any plugins which are not part of the core repository, because third-party plugins are independently owned and maintained. +- **Prereleases.** Features or functionality added in prerelease versions may be removed before the final release of that version. +- **Experimental features.** Features which are documented as experimental or otherwise noted in documentation to be exempt from compatibility guarantees. +- **External systems.** Compatibility is not guaranteed for interop with external deployment, execution, and process supervision software (such as containers and init systems). +- **Protocols.** Protocol-specific options and default settings such as those related to TCP, HTTP, TLS, etc. (For example, Caddy may change its defaults or phase out support for old or weak TLS versions or cipher suites at any time.) + +We recommend users always check the release notes before upgrading, and deploy servers to staging or test environments before production. + +Subject to the availability of stable ports of Go, Caddy binaries will continue to be supported for at least the following platforms: + +- **Linux:** 386, amd64, arm, arm64 +- **macOS:** amd64 +- **Windows:** amd64 +- **FreeBSD:** amd64 + +We chose these because they are popular and, based on historical trends, we suspect Go will continue to have good support for them in the foreseeable future. + +_DISCLAIMER: This guarantee is not a legally-binding contract. The Caddy developers, maintainers, authors, and contributors will not be held liable based on this document. Users accept and acknowledge that compatibility guarantees are based on good faith efforts by the developers, but ultimately the responsibility of stability in your production infrastructure is your own._ \ No newline at end of file diff --git a/Compatibility-Notice.md b/Compatibility-Notice.md deleted file mode 100644 index 2edcdb8..0000000 --- a/Compatibility-Notice.md +++ /dev/null @@ -1,7 +0,0 @@ -Caddy is not yet 1.0, meaning that individual releases are deemed stable, but Caddy may change between releases in a way that is not backward-compatible. - -*Caddy is not a good fit for every production use case, especially complex ones. However, it should receive some use in the wild in order to be improved (doesn't always mean adding features though).* - -The more use Caddy gets, the quicker we will reach a stable 1.0. And as Caddy gets closer to 1.0, the overall frequency and magnitude of breaking changes will decrease exponentially. - -If this is of interest to you, please use Caddy and get involved with its development to accelerate our pace to 1.0. \ No newline at end of file