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
   

   View Slide

2. View Slide

3. Not about Brexit
   

   View Slide

4. Not about Brexit
   (thankfully)
   

   View Slide

5. AGENDA
   WHAT WILL WE LOOK AT?
   Versioning 101
   Use the Packaging, Luke
   Deprecations and Removals
   Documenting Your Changes
   Wrap Up
   

   View Slide

6. Working at
   Working on since ~2015
   Contributor to too many Python projects
   WHO IS
   STEPHENFIN?
   

   View Slide

7. VERSIONING 101
   WHY IS VERSIONING IMPORTANT
   AND WHY SHOULD I BOTHER?
   

   View Slide

8. Does your software have users?
   Is your software expected to change or evolve?
   

   View Slide

9. View Slide

10. 1.2.3.rc2.dev1
    

    View Slide

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
    

    View Slide

12. USE THE
    PACKAGING, LUKE
    USING PACKAGING TOOLS FOR
    FUN AND PROFIT $$$
    

    View Slide

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

    View Slide

14. View Slide

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

    View Slide

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

    View Slide

17. $ git tag -a 1.0.0 -m 'Version 1.0.0'
    $ python setup.py sdist
    $ twine upload dist/*
    

    View Slide

18. View Slide

19. DEPRECATIONS
    AND REMOVALS
    DOCUMENTATION IN THE CODE,
    FOR AN EASIER LIFE
    

    View Slide

20. Developers hate writing docs. Solution?
    

    View Slide

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

    View Slide

22. View Slide

23. View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

28. DEBTCOLLECTOR
    from debtcollector import moves
    def bar():
    return 1
    foo = moves.moved_function(
    bar, 'foo', __name__,
    version='1.0', removal_version='2.0')
    

    View Slide

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
    

    View Slide

30. View Slide

31. DOCUMENTING
    YOUR CHANGES
    BRING OUT YOUR INNER TECH
    WRITER...OR NOT. LET’S JUST
    WRITE SOMETHING
    

    View Slide

32. View Slide

33. View Slide

34. View Slide

35. TOWNCRIER
    

    View Slide

36. TOWNCRIER
    $ cat <<< EOF > changes/123.feature.rst
    Add a new feature, ``foo``, to bar.
    EOF
    

    View Slide

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.
    

    View Slide

38. View Slide

39. RENO
    

    View Slide

40. RENO
    $ reno new foo
    Created new notes file in
    releasenotes/notes/foo-de3795c.yaml
    

    View Slide

41. RENO
    $ cat releasenotes/notes/foo-de3795c.yaml
    ___
    features:
    - |
    Add a new feature, ``foo``, to bar.
    

    View Slide

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.
    

    View Slide

43. View Slide

44. View Slide

45. View Slide

46. Kidding.
    

    View Slide

47. WRAP UP
    WHAT DID WE LOOK AT?
    Versioning 101
    Use the Packaging, Luke
    Deprecations and Removals
    Documenting Your Changes
    

    View Slide

48. THANK YOU!
    

    View Slide