add RFC007: API Stability Policy
Andrew Gerrand
9 years ago
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 |