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 full-size slide

  2. Not about Brexit

    View full-size slide

  3. Not about Brexit
    (thankfully)

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  8. 1.2.3.rc2.dev1

    View full-size slide

  9. 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 full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  16. Developers hate writing docs. Solution?

    View full-size slide

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

    View full-size slide

  18. 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 full-size slide

  19. 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 full-size slide

  20. 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 full-size slide

  21. 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 full-size slide

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

    View full-size slide

  23. 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 full-size slide

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

    View full-size slide

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

    View full-size slide

  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.

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  29. 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 full-size slide

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

    View full-size slide