Releasing Calendar Versioned Software (PyCon AU 2016)

Transcript

1. Releasing Calendar Versioned Software PyCon Australia, 2016

2. Hello, I’m Amber Brown (HawkOwl)

3. @hawkieowl atleastfornow.net

4. None

5. I live in Perth, Western Australia but Melbourne soon...

6. None

7. @hawkieowl "Releasing Calendar Versioned Software" Release Manager for: 13.2 14.0

   15.0, 15.1, 15.2, 15.3, 15.4, 15.5 16.0, 16.1, 16.2, 16.3, 16.4

8. @hawkieowl "Releasing Calendar Versioned Software" Other Projects twisted/treq twisted/klein twisted/pydoctor

   hawkowl/rproxy

9. (image by isometri.cc)

10. Versioning

11. @hawkieowl "Releasing Calendar Versioned Software" Consistency in your software's characteristics

12. @hawkieowl "Releasing Calendar Versioned Software" trunk now != trunk later

13. @hawkieowl "Releasing Calendar Versioned Software" Version X now == Version

    X later

14. @hawkieowl "Releasing Calendar Versioned Software" Upgrading to Version Y is

    explicit, repeatable

15. @hawkieowl "Releasing Calendar Versioned Software" Different kinds of versions for

    different release types

16. @hawkieowl "Releasing Calendar Versioned Software" Feature releases Bugfix releases Repackagings

17. @hawkieowl "Releasing Calendar Versioned Software" Makes your software easier to

    use, deploy

18. @hawkieowl "Releasing Calendar Versioned Software" What do we have to

    choose from?

19. @hawkieowl "Releasing Calendar Versioned Software" SemVer "Semantic versioning"

20. @hawkieowl "Releasing Calendar Versioned Software" CalVer "Calendar versioning"

21. @hawkieowl "Releasing Calendar Versioned Software" Chaos "meh just increment it"

22. @hawkieowl "Releasing Calendar Versioned Software"

23. SemVer

24. Given a version number MAJOR.MINOR.PATCH, increment the: 1. MAJOR version

    when you make incompatible API changes, 2. MINOR version when you add functionality in a backwards-compatible manner, and 3. PATCH version when you make backwards- compatible bug fixes. - semver.org

25. @hawkieowl "Releasing Calendar Versioned Software" breaking.feature.bugfix

26. @hawkieowl "Releasing Calendar Versioned Software" 1.0.0 Initial stable release

27. @hawkieowl "Releasing Calendar Versioned Software" 1.1.0 Backwards-compatible feature added

28. @hawkieowl "Releasing Calendar Versioned Software" 1.1.1 Backwards-compatible bug fix

29. @hawkieowl "Releasing Calendar Versioned Software" 2.0.0 Functionality changed in a

    way that breaks existing code, or removed feature

30. Why SemVer?

31. @hawkieowl "Releasing Calendar Versioned Software" Fits well with planning, roadmaps,

    "top-down"

32. @hawkieowl "Releasing Calendar Versioned Software" Easy to see if a

    release will work with your codebase

33. @hawkieowl "Releasing Calendar Versioned Software" package>=1.0,<2.0 Will match 1.0.0, 1.1.0,

    etc Won't match 2.0, 3.2, etc

34. @hawkieowl "Releasing Calendar Versioned Software" Encourages developers to break APIs

    more sparingly

35. @hawkieowl "Releasing Calendar Versioned Software" Easy for developers to understand

    and use to communicate intent

36. Why SemVer does not fit reality

37. @hawkieowl "Releasing Calendar Versioned Software" Production software is too complex

    to tell if any change is a breaking one

38. @hawkieowl "Releasing Calendar Versioned Software" No such thing as a

    "safe release"

39. @hawkieowl "Releasing Calendar Versioned Software" Doesn't scale well to complex

    software (frameworks, languages, operating systems)

40. @hawkieowl "Releasing Calendar Versioned Software" Chrome Versioning Syndrome

41. @hawkieowl "Releasing Calendar Versioned Software" Forces your whole codebase to

    operate in lockstep regarding deprecations, removals

42. @hawkieowl "Releasing Calendar Versioned Software" "The Big 2.0" (or 3.0!)

    kills projects

43. @hawkieowl "Releasing Calendar Versioned Software" "It's okay, we can update

    the major version number" hurts your users

44. @hawkieowl "Releasing Calendar Versioned Software" Large userbases on old major

    versions means you have to backport security fixes

45. @hawkieowl "Releasing Calendar Versioned Software" "Agile" developed software does not

    fit a "top down" model

46. @hawkieowl "Releasing Calendar Versioned Software" Is there a better way

    to serve our users?

47. CalVer

48. @hawkieowl "Releasing Calendar Versioned Software" Released not according to features,

    but time

49. @hawkieowl "Releasing Calendar Versioned Software" Firm schedules: Ubuntu Django (ish)

50. @hawkieowl "Releasing Calendar Versioned Software" Loose schedules: Twisted/Klein/Treq, youtube_dl, pytz

51. @hawkieowl "Releasing Calendar Versioned Software" year.month.patch year.month.day[.patch] year.release.patch

52. @hawkieowl "Releasing Calendar Versioned Software" Ubuntu 16.04.1 youtube_dl 2016.08.07 Twisted

    16.3.0

53. @hawkieowl "Releasing Calendar Versioned Software" Reduce the friction for a

    user to upgrade constantly

54. @hawkieowl "Releasing Calendar Versioned Software" Constantly stable

55. @hawkieowl "Releasing Calendar Versioned Software" Promise no breaking changes without

    deprecations, ever* *(or at least without a very good reason)

56. @hawkieowl "Releasing Calendar Versioned Software" Deprecated functionality removed after a

    period of time

57. @hawkieowl "Releasing Calendar Versioned Software" Usually one true release (the

    current one)

58. @hawkieowl "Releasing Calendar Versioned Software" Compatible with LTS strategies

59. @hawkieowl "Releasing Calendar Versioned Software" But it's not a silver

    bullet

60. Realities of Software

61. @hawkieowl "Releasing Calendar Versioned Software" Bugs will happen

62. @hawkieowl "Releasing Calendar Versioned Software" Regressions will happen

63. @hawkieowl "Releasing Calendar Versioned Software" How you manage them dictates

    the quality of your releases

64. @hawkieowl "Releasing Calendar Versioned Software" CalVer is the acceptance that

    software is constantly changing

65. @hawkieowl "Releasing Calendar Versioned Software" Effective calver requires you adopt

    better processes

66. @hawkieowl "Releasing Calendar Versioned Software" You must ensure every change

    does not affect a public API

67. @hawkieowl "Releasing Calendar Versioned Software" You need processes in place

    for deprecations, you'll be doing them a lot

68. Implementing CalVer

69. @hawkieowl "Releasing Calendar Versioned Software" Your goals dictate your release

    schedule

70. @hawkieowl "Releasing Calendar Versioned Software" Strict schedules mean more dependable

    upgrade cycles

71. @hawkieowl "Releasing Calendar Versioned Software" Strictly scheduled releases work well

    when you have one or two releases/yr

72. @hawkieowl "Releasing Calendar Versioned Software" Operating systems, enterprise software

73. @hawkieowl "Releasing Calendar Versioned Software" Loose schedules mean that you

    can release as often as there's features or fixes you want in the user's hands

74. @hawkieowl "Releasing Calendar Versioned Software" Loosely scheduled releases work well

    when you want 5+ releases/yr

75. @hawkieowl "Releasing Calendar Versioned Software" Software that talks to external

    services, software with security implications, libraries/frameworks

76. @hawkieowl "Releasing Calendar Versioned Software" Django has 1 release/8mo Twisted

    has ~5 releases/yr, youtube_dl has 1-2 a week

77. Deprecation Policies

78. @hawkieowl "Releasing Calendar Versioned Software" Deprecation policies must scale with

    your releases, plus your userbase

79. @hawkieowl "Releasing Calendar Versioned Software" Twisted requires 1 year of

    deprecation (as long as two releases have happened in the meantime)

80. @hawkieowl "Releasing Calendar Versioned Software" Django requires 8-16mo of deprecation

    (Django uses a semver/calver hybrid, with "LTS" releases)

81. Alter your QA

82. @hawkieowl "Releasing Calendar Versioned Software" Constantly changing software needs to

    have different QA processes

83. @hawkieowl "Releasing Calendar Versioned Software" Compensate for the lack of

    rigid alphas/betas with automated testing

84. @hawkieowl "Releasing Calendar Versioned Software" More tests == less likelihood

    of regressions

85. @hawkieowl "Releasing Calendar Versioned Software" Issue release candidates and encourage

    users to run their tests against it

86. Regressions: The Enemy of Frequent Releases

87. @hawkieowl "Releasing Calendar Versioned Software" Q: What is a regression?

    A: When user's software stops working through no fault of their own.

88. @hawkieowl "Releasing Calendar Versioned Software" Python import locations Argument names

    + types Return value types Behaviour

89. @hawkieowl "Releasing Calendar Versioned Software" Declare that "no breaking changes"

    only applies to public API!

90. @hawkieowl "Releasing Calendar Versioned Software" How can we introduce fewer

    regressions?

91. Have A Clear Public API

92. @hawkieowl "Releasing Calendar Versioned Software" Public module.MyClass Private module._MyClass _module.MyClass

    (ish*) *If _module.MyClass is accessible through a public function, it is public

93. @hawkieowl "Releasing Calendar Versioned Software" Abstract interfaces over concrete implementations

94. @hawkieowl "Releasing Calendar Versioned Software" "Returns an implementor of ISomething"

    vs "Returns Something"

95. @hawkieowl "Releasing Calendar Versioned Software" As long as the public

    API stays the same, everything else can change

96. @hawkieowl "Releasing Calendar Versioned Software" Test ONLY using your public

    API

97. @hawkieowl "Releasing Calendar Versioned Software" Instead of mocks, use explicitly

    passed fakes that implement the same interface as the real thing

98. @hawkieowl "Releasing Calendar Versioned Software" Mock-based testing means you may

    hide bugs in the underlying layers!

99. @hawkieowl "Releasing Calendar Versioned Software" "Slow Down, Compose Yourself" Amber

    Brown, PyCon AU 2015

100. Re-Export Functionality

101. @hawkieowl "Releasing Calendar Versioned Software" __all__ is a hint as

     to what is exported

102. @hawkieowl "Releasing Calendar Versioned Software" __all__ only affects import *,

     not from x import y!

103. @hawkieowl "Releasing Calendar Versioned Software" Write private modules, re-export into

     a public one

104. @hawkieowl "Releasing Calendar Versioned Software" logger _observer _formatting LogPublisher LogFormatter

105. @hawkieowl "Releasing Calendar Versioned Software" logger LogPublisher LogFormatter

106. @hawkieowl "Releasing Calendar Versioned Software" Can't accidentally export implementation details

107. Track Your Performance

108. @hawkieowl "Releasing Calendar Versioned Software" Performance degredation breaks software with

     performance constraints

109. @hawkieowl "Releasing Calendar Versioned Software" Microbenchmarks (Black Box)

110. @hawkieowl "Releasing Calendar Versioned Software"

111. @hawkieowl "Releasing Calendar Versioned Software" Macrobenchmarks (Integration)

112. @hawkieowl "Releasing Calendar Versioned Software"

113. Implement Code Review

114. @hawkieowl "Releasing Calendar Versioned Software" Twisted review process means we

     have a lower defect/LoC than most

115. @hawkieowl "Releasing Calendar Versioned Software" Most of these things can't

     (yet!) be detected by tools

116. What Aren't Regressions

117. @hawkieowl "Releasing Calendar Versioned Software" Security fixes

118. @hawkieowl "Releasing Calendar Versioned Software" Patching known vulnerabilities should be

     done backwards compatibly if possible

119. @hawkieowl "Releasing Calendar Versioned Software" Removing outright broken code (hasn't

     compiled for years, or doesn't work in dangerous ways)

120. @hawkieowl "Releasing Calendar Versioned Software" Have a process so that

     breaking changes are as unsurprising as possible

121. Safely Making Breaking Changes

122. @hawkieowl "Releasing Calendar Versioned Software" Deprecation is how you remove

     unwanted public API

123. @hawkieowl "Releasing Calendar Versioned Software" raise DeprecationWarning("no")

124. @hawkieowl "Releasing Calendar Versioned Software" @deprecated( Version("Twisted", 16, 4, 0),

     "Use newfunc instead.") def oldfunc(): return "wrong"

125. @hawkieowl "Releasing Calendar Versioned Software" DeprecationWarning: oldfunc was deprecated in

     Twisted 16.4.0: Use newfunc instead.

126. @hawkieowl "Releasing Calendar Versioned Software" Make old APIs shims over

     new ones, if possible

127. @hawkieowl "Releasing Calendar Versioned Software" Encourage your users to run

     Python with -Wd

128. @hawkieowl "Releasing Calendar Versioned Software" Remove it later, according to

     your deprecation policy

129. @hawkieowl "Releasing Calendar Versioned Software" Don't remove too much at

     once!

130. Tools To Help

131. @hawkieowl "Releasing Calendar Versioned Software" Streamline your NEWS file! github.com/hawkowl/towncrier

132. @hawkieowl "Releasing Calendar Versioned Software" Rich, comparable versions github.com/twisted/incremental

133. @hawkieowl "Releasing Calendar Versioned Software" Combine coverage between Travis, BuildBot,

     AppVeyor, Jenkins, et al codecov.io

134. @hawkieowl "Releasing Calendar Versioned Software" Repeatable, automated testing environments tox.readthedocs.io

135. tl;dr: Six Steps To CalVer

136. Step 1: Pick what CalVer properties you want

137. Step 2: Have a clear "public API"

138. Step 3: Ensure your test suite covers all the public

     API

139. Step 4: Release early, release often!

140. Step 5: If it sucks, deprecate it! ...but replace it

     first

141. Step 6: Don't break the user's software!

142. Questions? (pls no statements, save them for after)