Cheatsheet for 1.0.0 releases

In the past 3 years I have released several software packages and a few of them exceeded the 1.0.0 release. I am not confident with it. I need structure. I need a plan for 1.0.0 releases.

So what is the background? In software engineering the 1.0.0 release is a famous one. The release 1.0.0 is considered as the first public release where people can depend on the API/ABI.

Consider a car. With the public release a car seat customizer will look at the measurements and publish his customized seats for this type of car. The car company should not publish the same car with different seat measurements a month later. This would destroy the business for the customizer and annoy costumers. This is about standardization.

The same applies to software engineering. With the 1.0.0 release you are expected not to change the components in such a way that depending software breaks. Like the car seat measurements. If you stick to semantic versioning as defined by semver.org, you are actually allowed to make “incompatible API changes” if you release by incrementing the first of three numbers. Like python was backwards incompatible when going from the 2.x to 3.x release. But semantic versioning is not yet common enough in the industry. So I stick to the paradigm that the 1.0.0 release should be well-considered.

And this is my personal check list for 1.0.0 releases in the future:

  1. I will define a target audience and consider the social impact.
  2. I have a documentation for the public API accessible in the web.
  3. I have a working testsuite.
  4. I have written several programs using the API and concluded that the API is convienient to use with the languages’ builtin.
  5. I will check my API against best practices in the software paradigm I am using.
  6. I have money & time to provide hotfixes 24 hours after release at the latest.
  7. I will specify
    1. metadata such as: contributors, license, version, date, contact options, associated URLs
    2. dependencies and system requirements
    3. simple installation instructions for the most common usecase
    4. performance estimates
    5. target audience, pitfalls & limitations
    6. a changelog (at least for major and minor releases)

Iff all these requirements are met, go ahead and release it as 1.0.0, but not otherwise.

Cheatsheet for 1.0.0 releases

Python riddle

Python 3.4.3 (default, Mar 26 2015, 22:03:40) 
[GCC 4.9.2] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> a = 42
>>> def f():
...     x = a
...     a = 3
... 
>>> f()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<stdin>", line 2, in f
UnboundLocalError: local variable 'a' referenced before assignment

Now let’s skip the second row of f() and do not define “a = 3”. Guess, what is the result:

>>> a = 42
>>> def f():
...     x = a
... 
>>> f()
>>>

This works the same in python 2 and 3. To me it is non-intuitive behavior, but gives reason why reusing variable names is generally a bad idea.

Python riddle