WILL SOMEBODY
PLEASE TELL ME
WHAT IS GOING ON?
Stephen Finucane (@stephenfin)
FOSDEM 2020
Eric, the (very confused) giraffe
Slide 2
Slide 2 text
No content
Slide 3
Slide 3 text
Not about Brexit
Slide 4
Slide 4 text
Not about Brexit
(thankfully)
Slide 5
Slide 5 text
AGENDA
WHAT WILL WE LOOK AT?
Versioning 101
Use the Packaging, Luke
Deprecations and Removals
Documenting Your Changes
Wrap Up
Slide 6
Slide 6 text
Working at
Working on since ~2015
Contributor to too many Python projects
WHO IS
STEPHENFIN?
Slide 7
Slide 7 text
VERSIONING 101
WHY IS VERSIONING IMPORTANT
AND WHY SHOULD I BOTHER?
Slide 8
Slide 8 text
Does your software have users?
Is your software expected to change or evolve?
Slide 9
Slide 9 text
No content
Slide 10
Slide 10 text
1.2.3.rc2.dev1
Slide 11
Slide 11 text
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
Slide 12
Slide 12 text
USE THE
PACKAGING, LUKE
USING PACKAGING TOOLS FOR
FUN AND PROFIT $$$
Slide 13
Slide 13 text
from setuptools import setup
setup(
version='1.2.3.rc2.dev2',
...
)
setup.py
$ git tag -a 1.0.0 -m 'Version 1.0.0'
$ python setup.py sdist
$ twine upload dist/*
Slide 18
Slide 18 text
No content
Slide 19
Slide 19 text
DEPRECATIONS
AND REMOVALS
DOCUMENTATION IN THE CODE,
FOR AN EASIER LIFE
Slide 20
Slide 20 text
Developers hate writing docs. Solution?
Slide 21
Slide 21 text
Developers hate writing docs. Solution?
The code is the docs.
Slide 22
Slide 22 text
No content
Slide 23
Slide 23 text
No content
Slide 24
Slide 24 text
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
Slide 25
Slide 25 text
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
Slide 26
Slide 26 text
DEBTCOLLECTOR
from debtcollector import removals
@removals.removal(
version='1.0', removal_version='2.0',
message='Use the bar function instead')
def foo():
return 1
Slide 27
Slide 27 text
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
Slide 28
Slide 28 text
DEBTCOLLECTOR
from debtcollector import moves
def bar():
return 1
foo = moves.moved_function(
bar, 'foo', __name__,
version='1.0', removal_version='2.0')
Slide 29
Slide 29 text
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
Slide 30
Slide 30 text
No content
Slide 31
Slide 31 text
DOCUMENTING
YOUR CHANGES
BRING OUT YOUR INNER TECH
WRITER...OR NOT. LET’S JUST
WRITE SOMETHING
Slide 32
Slide 32 text
No content
Slide 33
Slide 33 text
No content
Slide 34
Slide 34 text
No content
Slide 35
Slide 35 text
TOWNCRIER
Slide 36
Slide 36 text
TOWNCRIER
$ cat <<< EOF > changes/123.feature.rst
Add a new feature, ``foo``, to bar.
EOF
Slide 37
Slide 37 text
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.
Slide 38
Slide 38 text
No content
Slide 39
Slide 39 text
RENO
Slide 40
Slide 40 text
RENO
$ reno new foo
Created new notes file in
releasenotes/notes/foo-de3795c.yaml
Slide 41
Slide 41 text
RENO
$ cat releasenotes/notes/foo-de3795c.yaml
___
features:
- |
Add a new feature, ``foo``, to bar.
Slide 42
Slide 42 text
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.
Slide 43
Slide 43 text
No content
Slide 44
Slide 44 text
No content
Slide 45
Slide 45 text
No content
Slide 46
Slide 46 text
Kidding.
Slide 47
Slide 47 text
WRAP UP
WHAT DID WE LOOK AT?
Versioning 101
Use the Packaging, Luke
Deprecations and Removals
Documenting Your Changes