Releasing Calendar Versioned Software (PyCon AU 2016)

Releasing Calendar Versioned Software (PyCon AU 2016)

3d37232726396a1d3c7412dd915095ea?s=128

Amber Brown (HawkOwl)

August 14, 2016
Tweet

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)