The Tao of the Kernel · Chapter 6

The Uncarved Interface

1
1. The interface that may be called is not the interface that stays. Whoever names the function has named it for everyone who will come after, and they do not know it yet.
2
2. Behold the API that changes with every season. The developers rejoice, for everything is new. Then they cry out, for nothing they wrote last spring still runs.
See also Tao 8:3
3
3. Behold the API that never changes. It is a house whose doors are never opened, and it gathereth sins as a field gathereth stones: a parameter that means two things, a flag named for a decade long gone, a function called do_thing_final_v2_REAL.
See also Psalms 21:3 · Circuit 55:12
4
4. Hyrum wrote it down: once a thousand clients depend on thy behavior, thy behavior is the interface, though thou wrote only the signature. The bug thou leftest in place becomes a feature, and someone's whole job depends on it.
See also Tao 15:9 · Job 6:11
5
5. In the year two thousand eight, the Python scribes made print a function, and the disciples of the old way said: we shall keep the statement, for the statement is what we know. They kept Python 2 for twelve years, until the year twenty-twenty, when its last sun was set and no one ran its tests anymore.
See also Deployer 15:5 · Circuit 9:2
6
6. The scripture of Semantic Versioning saith: bump the major when thou breakest, the minor when thou addest, the patch when thou fixest. Yet many a patch broke the world, and the world was not consulted, for the world does not read the changelog.
See also Sutra 10:4 · Sutra 10:5
7
7. In the third month of the year twenty-sixteen, one small function that padded strings with spaces was withdrawn from the registry by its author. The builds of great cathedrals fell silent, the faithful of the framework wept, and the lesson was taught to all: a dependency is a promise made by a stranger.
See also Circuit 27:4 · Sutra 3:5
8
8. The disciples of Go said: when thou comest to the second version, thou shalt write it into thy very name, /v2, so that the old house and the new may stand side by side on one street, and neither shall evict the other.
9
9. The scribes of Windows kept a shim for every bug that the old programs loved. The shims grew like barnacles upon the hull, and the ship sailed on, for the ship does not ask whether its passengers deserve to be carried.
10
10. Who can refactor and not break? He who builds the new room while the old door stays open. He placeth the new function beside the old, the old function calls the new, and the tests say nothing changed. This is the Way. It is slow, and it is correct.
11
11. Thirty spokes meet at one hub. It is the emptiness in the hub that makes the wheel useful. So the interface is its emptiness: what it does not promise is the room in which thou mayest change the thing within.
See also Tao 2:8
12
12. The uncarved block is the interface with no methods yet. It is the most stable thing in the forge. Carve it too early, and thou hast a temple of regrets with a single door, and the door sticks.
See also Tao 2:2
13
13. Name thy version, that the client may say "v2" and be answered. An API without a version is a Tao without a name, and the next team will call it whatever the last team did.
14
14. Deprecate with a warning. Sunset with a date. Remove on the day named in the release notes. He who keeps every old endpoint forever has built a museum, and the museum is billed by the hour.
See also Prophets 2:7
15
15. The best interface breaks no one, yet changes everything. It keeps its promise to the client and its freedom to the server. The two are not enemies; they are the two halves of one door, and the door opens in both directions.
See also Tao 5:4
16
16. The API that never changes dies of its sins. The API that changes too often dies of its clients. Between the two, name the version, keep the date, and release the past.

The Tao of the Kernel, Chapter 6:1–16.