Manuscript fails to build: pandoc-manubot-cite invalid api version 1.20

[habi]

I've updated my rootstock-derived manuscript with some issued mentioned from the journal editorial check.

On push, the manuscript fails to build with this error:

TypeError: ('invalid api version', [1, 20])
Error running filter pandoc-manubot-cite:
Filter returned error status 1
Error: Process completed with exit code 83.

Prior to this change, my manuscript built just fine, I guess/hope the problem is unrelated to my changes.

How can I make it build again?

[fmsabatini]

Hi, I was having the same problem:
https://github.com/fmsabatini/sPlotOpen_Manuscript/actions/runs/354512839
I updated rootstock and it now seems to work
https://github.com/manubot/rootstock/blob/master/SETUP.md#merging-upstream-rootstock-changes

[dhimmel]

Thanks for the quick reports! This issue was caused by the release of panflute 2.0.3, which dropped support for older versions of the Pandoc data structure.

How to fix this:

1. add panflute=1.12.5 as a conda dependency in build/environment.yml (as in aaefe9a).
2. upgrade rootstock to the latest version using the instructions here

1 is easier, 2 is preferable. Am happy to help if you run into issues. I could even submit a PR to do 2.

[dhimmel]

To clarify the extent of the problem, all manuscript instances running old versions of Rootstock will begin failing. I think we've only had an issue like this once before. It's severe and points to the importance of reproducible computational environments. Switching from conda to docker would add an extra layer of protection, so that is on our roadmap.

[habi]

Thanks for the super-quick response and fix.
The preferable fix 2 worked well: habi/zmk-tooth-cohort-method-manuscript#11 now I'm off to re-submitting an updated PDF :)

[habi]

To clarify the extent of the problem, all manuscript instances running old versions of Rootstock will begin failing.

I think it's an important issue to tackle, but it seems that upgrading to the newest rootstock version isn't that involved.

[dhimmel]

I think it's an important issue to tackle, but it seems that upgrading to the newest rootstock version isn't that involved.

Yeah, it can depend on the number of conflicts that arise. For very old manuscripts, it can be a bit daunting.

@fmsabatini very cool manuscript at https://fmsabatini.github.io/sPlotOpen_Manuscript/. Feel free to add it to https://github.com/manubot/catalog.

[fmsabatini]

Will do!
Thanks for the indications, and for maintaining Manubot. With 160 coauthors, I'm really loving it

[agitter]

@dhimmel this issue is going to affect a lot of manuscripts. Should we make a more prominent announcement in this repository? Maybe pin this issue or even update the readme.

Thanks for fixing the underlying error quickly.

[dhimmel]

Maybe pin this issue

Good idea. I pinned the issue. We also can consider opening issues on public active manuscript instances linking to this issue and offering upgrade help if needed.

[dhimmel]

@agitter here is the source markdown for an issue I am beginning to post on affected repos. We can keep track of these comments via there incoming references to this issue. First line is title:

Manubot upgrade required to fix broken builds

Greetings Manubot manuscript user. On 2020-11-09, most Manubot manuscripts started encountering errors when building. This does not endanger the existing manuscript, but does make it so changes to the manuscript won't be automatically published by continuous integration.

The error occurs during `pandoc-manubot-cite` filter execution, when panflute detects an incompatible Pandoc version and raises `TypeError: ('invalid api version', [1, 20])`. The issue was triggered when version 2 of panflute was released, which dropped support for older Pandoc versions. We (the Manubot maintainers) had forgotten to pin the panflute dependency, so CI installs the most recent version from [PyPI](https://pypi.org/project/panflute/), which happens to be incompatible. See https://github.com/manubot/rootstock/issues/387 for more information.

The **suggested fix** is to update to the latest version of manubot/rootstock, as described in [SETUP: Merging upstream rootstock changes](https://github.com/manubot/rootstock/blob/master/SETUP.md#merging-upstream-rootstock-changes). We are happy to review upgrade pull requests (just mention it here). In addition, if you are having trouble upgrading, let us know and we can open a pull request to do so.

Upgrading to the current rootstock will also resolve https://github.com/manubot/rootstock/issues/388, which relates to the following message you might have seen in your GitHub Actions CI logs:

> The `set-env` command is deprecated and will be disabled on November 16th.

Thanks for being an early adopter of Manubot!

[agitter]

Great message @dhimmel. If you would like me to open more issues on active manuscripts, I can work on it Friday.