Will Someone *Please* Tell Me What's 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 FOSDEM 2020.

Transcript

1. WILL SOMEBODY PLEASE TELL ME WHAT IS GOING ON? Stephen Finucane (@stephenfin) FOSDEM 2020 Eric, the (very confused) giraffe
3. Not about Brexit
4. Not about Brexit (thankfully)
5. AGENDA WHAT WILL WE LOOK AT? Versioning 101 Use the Packaging, Luke Deprecations and Removals Documenting Your Changes Wrap Up
6. Working 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/*
19. DEPRECATIONS AND REMOVALS DOCUMENTATION IN THE CODE, FOR AN EASIER LIFE
20. Developers hate writing docs. Solution?
21. Developers hate writing docs. Solution? The code is the docs.
24. 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
25. 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
26. DEBTCOLLECTOR from debtcollector import removals @removals.removal( version='1.0', removal_version='2.0', message='Use the bar function instead') def foo(): return 1
27. 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
28. DEBTCOLLECTOR from debtcollector import moves def bar(): return 1 foo = moves.moved_function( bar, 'foo', __name__, version='1.0', removal_version='2.0')
29. 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
31. DOCUMENTING YOUR CHANGES BRING OUT YOUR INNER TECH WRITER...OR NOT. LET’S JUST WRITE SOMETHING
35. TOWNCRIER
36. TOWNCRIER $ cat <<< EOF > changes/123.feature.rst Add a new feature, ``foo``, to bar. EOF
37. 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.
39. RENO
40. RENO $ reno new foo Created new notes file in releasenotes/notes/foo-de3795c.yaml
41. RENO $ cat releasenotes/notes/foo-de3795c.yaml ___ features: - | Add a new feature, ``foo``, to bar.
42. 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.
46. Kidding.
47. WRAP UP WHAT DID WE LOOK AT? Versioning 101 Use the Packaging, Luke Deprecations and Removals Documenting Your Changes
48. THANK YOU!