Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Will Someone *Please* Tell Me What's Going On?

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.

Stephen Finucane

February 01, 2020
Tweet

More Decks by Stephen Finucane

Other Decks in Programming

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