Codebase list golang-github-go-kit-kit / 9ce7733
Merge pull request #12 from adg/master add RFC007: API Stability Policy Peter Bourgon 9 years ago
1 changed file(s) with 97 addition(s) and 0 deletion(s). Raw diff Collapse all Expand all
+97
-0
rfc/rfc007-api-stability.md less more
0 ---
1 RFC: 007
2 Author: Andrew Gerrand <adg@golang.org>
3 Status: Draft
4 ---
5
6 # API Stability Policy
7
8 ## Motivation
9
10 The gokit project depends on code maintained by others.
11 This includes the Go standard library and sub-repositories
12 and other external libraries.
13
14 The Go language and standard library provide stability guarantees, but the
15 other external libraries typically do not. This RFC proposes a standard policy
16 for package authors to advertise API stability.
17
18 The intention is that the gokit project will require that its dependencies
19 adhere to the policy, with the greater goal of improving the Go ecosystem
20 as a whole.
21
22 ## Scope
23
24 This policy is for package authors to provide their users with a promise of API
25 stability.
26 This document is similar to and inspired by the [Go 1 compatibility
27 promise](https://golang.org/doc/go1compat).
28
29 An author declaring their package "API Stable" makes the following promise:
30
31 > We will not change the package's exported API in backward incompatible ways.
32 > Future changes to this package will not break dependent code.
33
34 ### Coverage
35
36 The promise of stability includes:
37
38 * The package name,
39 * Exported type declarations and struct fields (names and types),
40 * Exported function and method names, parameters, and return values,
41 * Exported constant names and values,
42 * Exported variable names and values,
43 * The documented behavior of all exported code.
44
45 ### Exceptions
46
47 * Security. A security issue in the package may come to light whose resolution
48 requires breaking compatibility. We reserve the right to address such
49 security issues.
50
51 * Unspecified behavior. Programs that depend on unspecified
52 behavior may break in future releases.
53
54 * Bugs. If the package has a bug, a program that depends on the buggy behavior
55 may break if the bug is fixed. We reserve the right to fix such bugs.
56
57 * Struct literals. For the addition of features it may be necessary to add
58 fields to exported structs in the package API. Code that uses unkeyed struct
59 literals (such as pkg.T{3, "x"}) to create values of these types would fail
60 to compile after such a change. However, code that uses keyed literals
61 (pkg.T{A: 3, B: "x"}) will continue to compile after such a change. We will
62 update such data structures in a way that allows keyed struct literals to
63 remain compatible, although unkeyed literals may fail to compile. (There are
64 also more intricate cases involving nested data structures or interfaces, but
65 they have the same resolution.) We therefore recommend that composite
66 literals whose type is defined in a separate package should use the keyed
67 notation.
68
69 * Dot imports. If a program imports a package using import . "path", additional
70 names later defined in the imported package may conflict with other names
71 defined in the program. We do not recommend the use of import . outside of
72 tests, and using it may cause a program to fail to compile in the future.
73
74 ### Breaking compatibility
75
76 Should the author wish to break compatibility by redesigning the API the author
77 should create a new package with a new import path.
78
79 ### Awareness
80
81 This text should be present in a file named STABILITY in the repository root.
82
83 ### Enforcement
84
85 Tooling may be devised to check the stability of an API as a package evolves,
86 similar to the api tool used by the Go core.
87
88 The [vet](https://godoc.org/golang.org/x/tools/cmd/vet) tool will already
89 detect "untagged" struct literals; that is, struct literals that will break
90 when new fields are added to the struct.
91
92 ## Implementation
93
94 To be defined.
95
96