Skip to content

17th December 2021

Coding

Generic Coding Practices

Program Versioning

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:

  • 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:

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

Python Snippets

mkdocstrings

Poetry

  • Correction: Warn against upper version pinning.