Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Releasing Calendar Versioned Software (PyCon AU 2016)

Releasing Calendar Versioned Software (PyCon AU 2016)

3d37232726396a1d3c7412dd915095ea?s=128

Amber Brown (HawkOwl)

August 14, 2016
Tweet

More Decks by Amber Brown (HawkOwl)

Other Decks in Technology

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)