Keep a changelog?

[johncf]

In PyPI, version history lists these stable releases: 1.0.0, 1.0.1, 1.0.2, 1.1.0, 2.0.1, 2.1. These look independent from Pandoc releases. I wanted to find:

• What are the things I should keep in mind when switching from 1.1.0 to 2.x?
• Is there a supported version range of the system library for each of these releases?

[boisgera]

Hi @johncf!,

Great questions, since I do not address these issues in the documentation at all.

• The releases of Pandoc (Python library) are not identical, but not totally independent from the Pandoc releases. The 1.x to 2.x was caused by an API-breaking change that was specific to the Python version and nowadays, on the 2.x history, the Python version changes either to catch up with the releases of the Pandoc CLI or to introduce new APIs, fix bugs, etc.

• The 1.x design tried very hard not to require the Pandoc CLI tool. It was therefore essentially a conversion tool between the JSON format that the Pandoc CLI supports and a Python model. It was nicely decoupled ("do one thing and do it well"), but every real-life usage required you to use explicitly the Pandoc CLI tool to read/write the JSON data and the Python library. In the the design of the 2.x version, we assume that some version of the CLI tool is installed and wrap it so that you can do (almost) all you want in Python and the JSON pivot format becomes a mere implementation detail; it should therefore be more convenient to use. The two APIs are not compatible, but the new API is still very small (read, write, iter, optionally configure, see the API doc). The principle of a hierarchy of classes that represents all document elements is the same between the 1.x and 2.x branches.

• I am not working on the 1.x branch anymore ; it is not compatible with the recent versions of the Pandoc CLI. OTOH, I try to follow the releases of Pandoc (CLI) and catch up in the 2.x branch when I notice a change or when a library user pings me. My advice would be: migrate from 1.x to 2.x if it's a sensible option for you (or freeze everything otherwise), then install the latest Pypi release if you want to be able to use the most recent version of the Pandoc tool.

• The supported version range for the Pandoc tool is not documented ; it should be "(almost) everything" if you have the latest PyPi version of the Pandoc Python library. You can check that using an undocumented (internal) API :

  >>> import json
  >>> import pkg_resources  # setuptools
  >>> js = pkg_resources.resource_string("pandoc", "pandoc-types.js")
  >>> data = json.loads(js)
  >>> for v in data["version_mapping"]:
  ...     print(v)
  1.8
  1.8.0.1
  1.8.0.2
  1.8.0.3
  1.8.1
  1.8.1.1
  1.8.1.2
  1.8.2
  1.8.2.1
  1.9
  1.9.0.2
  1.9.0.3
  1.9.0.4
  1.9.0.5
  1.9.1
  1.9.1.1
  1.9.1.2
  1.9.2
  1.9.3
  1.9.4
  1.9.4.1
  1.9.4.2
  1.9.4.3
  1.9.4.4
  1.9.4.5
  1.10
  1.10.0.1
  1.10.0.2
  1.10.0.3
  1.10.0.4
  1.10.0.5
  1.10.1
  1.11
  1.11.1
  1.12
  1.12.0.1
  1.12.0.2
  1.12.1
  1.12.2
  1.12.2.1
  1.12.3
  1.12.3.1
  1.12.3.2
  1.12.3.3
  1.12.4
  1.12.4.2
  1.13
  1.13.0.1
  1.13.1
  1.13.2
  1.13.2.1
  1.14
  1.14.0.1
  1.14.0.2
  1.14.0.3
  1.14.0.4
  1.14.1
  1.15
  1.15.0.1
  1.15.0.2
  1.15.0.3
  1.15.0.4
  1.15.0.5
  1.15.0.6
  1.15.1
  1.15.1.1
  1.15.2
  1.15.2.1
  1.16
  1.16.0.1
  1.16.0.2
  1.17
  1.17.0.1
  1.17.0.2
  1.17.0.3
  1.17.1
  1.17.2
  1.18
  1.19
  1.19.1
  1.19.2
  1.19.2.1
  1.19.2.2
  1.19.2.3
  1.19.2.4
  2.0
  2.0.0.1
  2.0.1
  2.0.1.1
  2.0.2
  2.0.3
  2.0.4
  2.0.5
  2.0.6
  2.1
  2.1.1
  2.1.2
  2.1.3
  2.2
  2.2.1
  2.2.2
  2.2.2.1
  2.2.3
  2.2.3.1
  2.2.3.2
  2.3
  2.3.1
  2.4
  2.5
  2.6
  2.7
  2.7.1
  2.7.2
  2.7.3
  2.8
  2.8.0.1
  2.8.1
  2.9
  2.9.1
  2.9.1.1
  2.9.2
  2.9.2.1
  2.11
  2.11.0.1
  2.11.0.2
  2.11.0.3
  2.11.0.4
  2.11.1
  2.11.1.1
  2.11.2
  2.11.3
  2.11.3.1
  2.11.3.2
  2.11.4
  2.12
  2.13
  2.14
  2.14.0.1
  2.14.0.2
  2.14.0.3
  2.14.1
  2.14.2
  2.15
  2.16
  2.16.1
  2.16.2
  2.17
  2.17.0.1
  2.17.1
  2.17.1.1

• and finally you are right, a changelog would definitely help ☺️.

Cheers,

SB

[boisgera]

and finally you are right, a changelog would definitely help ☺️.

Started the changelog with the 2.2 release: https://boisgera.github.io/pandoc/changelog/