Will somebody *please* tell me what is going on?

Will somebody *please* tell me what is going on?

Software rarely stands still (unless it's TeX). Things are added, things are removed, things break and are then hopefully fixed. Managing this, from both the developer and user perspective, can be tough. In this talk we examine and compare some of the tools that one can use to make this process easier, such as 'debtcollector', 'reno' and 'towncrier', and contrast these with alternatives used in other projects. This talk would mainly be of interest to developers of open source libraries, though the same tooling can be used for any Python library or application that wishes to maintain stable interfaces and/or document changes in their product.

This was presented at PyCon Limerick 2019.

8fbd28ad59a1aa317a5ec175b0778359?s=128

Stephen Finucane

March 23, 2019
Tweet

Transcript

  1. WILL SOMEBODY PLEASE TELL ME WHAT IS GOING ON? Stephen

    Finucane (@stephenfin) PyCon Limerick 2019 Eri , t e (ve c se ) gi f
  2. None
  3. Not about Brexit

  4. Not about Brexit (thankfully)

  5. AGENDA WHAT WILL WE LOOK AT? Versioning 101 Use the

    Packaging, Luke Documenting Your Changes Deprecations and Removals Wrap Up
  6. Formerly of , now at Working on since ~2015 Contributor

    to too many Python projects WHO IS STEPHENFIN?
  7. VERSIONING 101 WHY IS VERSIONING IMPORTANT AND WHY SHOULD I

    BOTHER?
  8. Does your software have users? Is your software expected to

    change or evolve?
  9. None
  10. 1.2.3.rc2.dev1

  11. SEMANTIC (a.k.a. SemVer) CALENDAR (a.k.a. CalVer) 18 . 02 .

    1 Major Minor Patch 2 . 1 . 1 Month Micro Very common. Used by a *lot* of packages Less common. Most likely seen in Ubuntu, DPDK Year
  12. USE THE PACKAGING, LUKE USING PACKAGING TOOLS FOR FUN AND

    PROFIT $$$
  13. from setuptools import setup setup( version='1.2.3.rc2.dev2', ... ) setup.py

  14. None
  15. SETUPTOOLS-SCM from setuptools import setup setup( setup_requires=[ 'setuptools_scm', ], use_scm_version=True,

    ... ) setup.py
  16. PBR from setuptools import setup setup( setup_requires=[ 'pbr', ], pbr=True,

    ... ) setup.py
  17. $ git tag -a 1.0.0 -m 'Version 1.0.0' $ python

    setup.py sdist $ twine upload dist/*
  18. DOCUMENTING YOUR CHANGES BRING OUT YOUR INNER TECH WRITER...OR NOT.

    LET’S JUST WRITE SOMETHING
  19. None
  20. None
  21. None
  22. None
  23. None
  24. TOWNCRIER

  25. TOWNCRIER $ cat <<< EOF > changes/123.feature.rst Add a new

    feature, ``foo``, to bar. EOF
  26. TOWNCRIER $ towncrier --draft Loading template... Finding news fragments... Rendering

    news fragments... Draft only -- nothing has been written. What is seen below is what would be written. v1.0.0 (2019-01-01) ------------------- Features ^^^^^^^^ - Add a new feature, ``foo``, to bar.
  27. RENO

  28. RENO $ reno new foo Created new notes file in

    releasenotes/notes/foo-de3795c.yaml
  29. RENO $ cat releasenotes/notes/foo-de3795c.yaml ___ features: - | Add a

    new feature, ``foo``, to bar.
  30. RENO $ reno report --version 1.0.0 --no-show-source ============= Release Notes

    ============= .. _Release Notes_1.0.0: 1.0.0 ===== .. _Release Notes_1.0.0_New Features: New Features ------------ - Add a new feature, ``foo``, to bar.
  31. DEPRECATIONS AND REMOVALS DOCUMENTATION IN THE CODE, FOR AN EASIER

    LIFE
  32. Developers hate writing docs. Solution?

  33. Developers hate writing docs. Solution? The code is the docs.

  34. None
  35. None
  36. DEPRECATION import deprecation @deprecation.deprecated( deprecated_in='1.0', removed_in='2.0', details='Use the bar function

    instead') def foo(): return 1 foobar.py
  37. DEPRECATION $ python >>> import foobar >>> foobar.foo() __main__:1: DeprecatedWarning:

    foo is deprecated as of 1.0 and will be removed in 2.0. Use the bar function instead 1
  38. DEBTCOLLECTOR from debtcollector import removals @removals.removal( version='1.0', removal_version='2.0', message='Use the

    bar function instead') def foo(): return 1
  39. DEBTCOLLECTOR $ python >>> import foobar >>> foobar.foo() __main__:1: DeprecationWarning:

    Using function/method 'baz()' is deprecated in version '1.0' and will be removed in version '2.0': Use the bar function instead 1
  40. DEBTCOLLECTOR from debtcollector import moves def bar(): return 1 foo

    = moves.moved_function( bar, 'foo', __name__, version='1.0', removal_version='2.0')
  41. DEBTCOLLECTOR $ python >>> import foobar >>> foobar.foo() __main__:1: DeprecationWarning:

    Function 'foobar.foo()' has moved to 'foobar.bar()' in version '1.0' and will be removed in version '2.0' 1
  42. None
  43. WRAP UP WHAT DID WE LOOK AT? Versioning 101 Use

    the Packaging, Luke Documenting Your Changes Deprecations and Removals
  44. THANK YOU!