Will somebody *please* tell me what is going on?

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.

8fbd28ad59a1aa317a5ec175b0778359?s=128

Stephen Finucane

March 23, 2019
Tweet

Transcript

  1. 1.

    WILL SOMEBODY PLEASE TELL ME WHAT IS GOING ON? Stephen

    Finucane (@stephenfin) PyCon Limerick 2019 Eri , t e (ve c se ) gi f
  2. 2.
  3. 5.

    AGENDA WHAT WILL WE LOOK AT? Versioning 101 Use the

    Packaging, Luke Documenting Your Changes Deprecations and Removals Wrap Up
  4. 6.

    Formerly of , now at Working on since ~2015 Contributor

    to too many Python projects WHO IS STEPHENFIN?
  5. 9.
  6. 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
  7. 14.
  8. 17.

    $ git tag -a 1.0.0 -m 'Version 1.0.0' $ python

    setup.py sdist $ twine upload dist/*
  9. 19.
  10. 20.
  11. 21.
  12. 22.
  13. 23.
  14. 24.
  15. 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.
  16. 27.
  17. 28.

    RENO $ reno new foo Created new notes file in

    releasenotes/notes/foo-de3795c.yaml
  18. 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.
  19. 34.
  20. 35.
  21. 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
  22. 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
  23. 40.

    DEBTCOLLECTOR from debtcollector import moves def bar(): return 1 foo

    = moves.moved_function( bar, 'foo', __name__, version='1.0', removal_version='2.0')
  24. 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
  25. 42.
  26. 43.

    WRAP UP WHAT DID WE LOOK AT? Versioning 101 Use

    the Packaging, Luke Documenting Your Changes Deprecations and Removals