17th December 2021

Coding⚑

Generic Coding Practices⚑

Program Versioning⚑

• New: Define how to use versioning in software.

  A long article on how to use versioning both as a developer and as a consumer. It includes:

  • Deciding what version system to use for your programs.
  • How to evolve your code version.
  • Deciding how to manage the versions of your dependencies.
  • A huge rant on Upper version pinning.
  • When to use lower version pinning.
  • How to automatically upgrade and test your dependencies.
  • Monitor your dependencies evolution.

Keep a Changelog⚑

• New: Introduce the Changelog practice.

  A changelog is a file which contains a curated, chronologically ordered list of notable changes for each version of a project.

  It's purpose is to make it easier for users and contributors to see precisely what notable changes have been made between each release (or version) of the project.

  In the article we added:

  • Guidelines on how to build good changelogs
  • How to reduce the effort required to maintain a changelog

• New: Introduce Semantic Versioning.

  Semantic Versioning is a way to define your program's version based on the type of changes you've introduced. It's defined as a three-number string (separated with a period) in the format of MAJOR.MINOR.PATCH.

  Also included in the article is:

  • When to do a major release.
  • Semantic versioning system problems.

Calendar Versioning⚑

• New: Introduce Calendar Versioning.

  Calendar Versioning is a versioning convention based on your project's release calendar, instead of arbitrary numbers.

  CalVer suggests version number to be in format of: YEAR.MONTH.sequence. For example, 20.1 indicates a release in 2020 January, while 20.5.2 indicates a release that occurred in 2020 May, while the 2 indicates this is the third release of the month.

Python⚑

Code Styling⚑

• Reorganization: Moved the semantic versioning commit guidelines to the semver article.

Package Management⚑

• New: Describe what a dependency solver does.

  A Solver tries to find a working set of dependencies that all agree with each other. By looking back in time, it’s happy to solve very old versions of packages if newer ones are supposed to be incompatible. This can be helpful, but is slow, and also means you can easily get a very ancient set of packages when you thought you were getting the latest versions.

  In the section we compare Pip's and Poetry's solver.

• New: Add downsides of Poetry.

  It does upper version capping by default, which is becoming a big problem in the Python environment.

  This is specially useless when you add dependencies that follow CalVer. poetry add packaging will still do ^21 for the version it adds. You shouldn’t be capping versions, but you really shouldn’t be capping CalVer.

  It's equally troublesome that it upper pins the python version.

Pytest⚑

• New: Capture deprecation warnings.

  Python and its ecosystem does not have an assumption of strict SemVer, and has a tradition of providing deprecation warnings. If you have good CI, you should be able to catch warnings even before your users see them. Try the following pytest configuration:

  [tool.pytest.ini_options]
  filterwarnings = ["error"]
  

  This will turn warnings into errors and allow your CI to break before users break.

  Other sections added are:

  • Ensuring code triggers a deprecation warning.
  • Asserting warnings with the warns function.
  • Recording warnings.

Python Snippets⚑

• New: IPv4 regular expression.

  regex = re.compile(
      r"(?<![-\.\d])(?:0{0,2}?[0-9]\.|1\d?\d?\.|2[0-5]?[0-5]?\.){3}"
      r'(?:0{0,2}?[0-9]|1\d?\d?|2[0-5]?[0-5]?)(?![\.\d])"^[0-9]{1,3}*$'
  )
  

• New: Remove the elements of a list from another.

  >>> set([1,2,6,8]) - set([2,3,5,8])
  set([1, 6])
  

mkdocstrings⚑

• New: How to write good test docstrings.

  Both without a template and using the Given When Then style.

Poetry⚑

• Correction: Warn against upper version pinning.

  The main problem is that poetry add does upper pinning of dependencies by default, which is a really bad idea.