The document discusses strategies for maintaining stable APIs in libraries to avoid breaking changes. It recommends upfront design work, README driven development, and treating each API decision as a permanent contract. Compatibility adapters and ethical deprecation with replacements can mitigate needed changes. Semantic versioning alone should not be used to justify breaking changes. The goal is for libraries to still work years later like Make, cron, and the Linux kernel by prioritizing users over code changes.

1. How not to rewrite
your library
Tips on stable APIs
by Loren Segal / @lsegal

2. I’ve worked on libraries,
all shapesand sizes.

3. I’ve worked on libraries,
all shapesand sizes.
and with
^

4. I’ve worked on libraries,
all shapesand sizes.
and with
^

5. I’ve worked on libraries,
all shapesand sizes.
and with
^

6. I’ve worked on libraries,
all shapesand sizes.
and with
^

7. cost benefit.

8. YMMV.

9. let’s go!

10. we’re getting older!

11. (and that’s a good thing)

12. what does it mean
to be a grownup?

13. responsibility.

14. there is a lot of Ruby
out there.

15. much more to break.

16. idealism ⟼ pragmatism

17. Backwards
Compatibility
Matters

18. to whom?

19. Dependency GraphLibrary Maintainer
parser
ast

20. easy mode.

21. library maintainers
have a distorted view
of dependency management.

22. Library Maintainer
“It’s just one
breaking change!”

23. reality is…

24. Dependency GraphApplication Maintainer

25. Dependency GraphApplication Maintainer
parser gem

26. reality is…

27. “It’s just one
breaking change!”
“It’s just one
breaking change!”
“It’s just one
breaking change!”
“It’s just one
breaking change!”
“It’s just one
breaking change!”
“It’s just one
breaking change!”
Application Maintainer

28. breaking changes hurt.

29. I’m Application Maintainer.
what can I do?

30. hold
library maintainers
accountable.

31. open issues.

32. even for major
version bumps.

33. I’m a Library Maintainer

34. avoidance > mitigation
change

35. but mitigation will do.

36. C H A N G E
MITIGATION
STRATEGIES

37. Compatibility
Adapters
Strategy #1

38. Adapter Pros:
- Minimal change for user.
- Write once, minimal
maintenance.

39. RedcarpetCompat
Only 74 lines.
Rarely changes.

40. “but it’s a maintenance burden!”

41. “but it’s a maintenance burden!”

42. Gem::SourceIndex
RubyGems 1.3 API.
Literally 0 changes.

43. Ethical Deprecation
Strategy #2

44. this is super important…

45. Deprecate ≠ Delete!
NOT EQUAL

46. dislike, don’t delete.

47. TOLERANCE!
We must live
in harmony with
our deprecated
brothers and sisters!

48. Good Deprecation Example

49. Java 1.3:
Thread.stop()
Java 1.3: Thread.stop()

50. Java 1.8: Still there.
Java 1.8: Thread.stop()

51. Deprecation Tips

52. 1.
always have a
good technical
reason to deprecate.

53. 2.
always have a
replacement API.

54. be like: Thread.stop()

55. be like: Thread.stop()
Good Reason

56. be like: strcpy()

57. be like: strcpy()
Alternative API

58. don’t be like: fs.exists()

59. don’t be like: fs.exists()

60. don’t be like: fs.exists()
Not technical.

61. don’t be like: fs.exists()
Not technical.
No reason provided.
No replacement provided.

62. 3.
you don’t have to
maintain deprecated
code.

63. 4.
you don’t have to
delete
deprecated code.

64. even in major version
updates.

65. Semantic Versioning
Strategy #3?

66. v{MAJOR}.{MINOR}.{PATCH}
MAJOR = breaking change
MINOR = non-breaking change
PATCH = no APIs should change

67. v{MAJOR}.{MINOR}.{PATCH}
v1.0.0
v3.5.3
etc.

68. SemVer is a great tool!

69. you can use SemVer.

70. you should use
SemVer!

71. just don’t use SemVer
as an excuse to break users.

72. just don’t use SemVer
as an excuse to break users.
that’s not cool.

73. major version bumps
are still last resorts.

74. only use SemVer to
communicate
breaking changes.
(the rare times they happen)

75. recall:
avoidance > mitigation

76. C H A N G E
AVOIDANCE
STRATEGIES

77. avoid breaking changes.

78. avoid breaking changes.
easy right?

79. Tips to Avoid Changing
Your API

80. 1.
up-front design work
always yields a more
stable API.*

81. 1.
up-front design work
always yields a more
stable API.*
* in my experience.

82. - domain model
- class diagram
- ER diagram
make a:

83. YARD, circa Feb. 2007

84. https://raw.githubusercontent.com/lsegal/yard/
v0.1a/doc/domain_model.jpg

85. 8 years later,
that entire architecture
still exists.

86. YARD,
circa 2015

87. 2.
README Driven
Development

88. sketch out your API
in README form.

89. start from user
experience,
work backwards.

90. start from user
experience,
work backwards.

91. less formal. equally helpful.

92. less formal. equally helpful.
for small libraries.

93. 3.
Everything as a
Contract

94. Think of each API
decision as a contract
you cannot break.

95. Ask:
“Will I be comfortable
with this API being
public in 5 years?”

96. If not, don’t make it public.

97. “But 5 years is a long time!”

98. no.

99. Things That Were
Designed More Than
5 Years Ago and
Still Work Today

100. cron (last change in 1999)

101. Linux Kernel.

102. (GNU/BSD) make.
10+ year old Makefiles
still work.

103. not bad.

104. (note: he probably didn’t vendor gcc/make/
X11 in his repository)

105. will you be able
to say this about your
non-trivial Ruby
program
in 20 years?

106. how about 10?

107. how about 5?

108. Lessons

109. 1.
design for the future.

110. 2.
think about your users.
users > code.

111. 3.
own your mistakes.

112. “Way too many projects seem to
think that the code is more
important than the user, and they
break things left and right, and they
don’t apologize for it, because they
feel that they are ‘fixing’ the code
and doing the right thing.”

113. “Way too many projects seem to
think that the code is more
important than the user, and they
break things left and right, and they
don’t apologize for it, because they
feel that they are ‘fixing’ the code
and doing the right thing.”
- Linus Torvalds, creator of the Linux Kernel

115. @lsegal
@lsegal
gnuu.org!
thank you.