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.

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
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?
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
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
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.
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
43. WRAP UP WHAT DID WE LOOK AT? Versioning 101 Use the Packaging, Luke Documenting Your Changes Deprecations and Removals
44. THANK YOU!