https://github.com/cilium/cilium
Revision 3eee19a17a23489bb9461e0526f42d7f71da35ed authored by Quentin Monnet on 16 January 2023, 13:56:21 UTC, committed by Quentin Monnet on 17 January 2023, 09:41:25 UTC
Once upon a time, Cilium docs used the openapi Sphinx add-on to generate
its API reference based on the code. And things were good.

One day, Dependabot raised a security alert, stating that Mistune v2.0.2
was vulnerable to catastrophic backtracking [0] - this is a regex
parsing thing. Mistune was a dependency to m2r, an add-on to parse
Markdown in Sphinx, which in turn was a dependency to openapi.

The easy path would have been to update m2r to use the latest, fixed
Mistune version; but m2r was incompatible with Mistune >= 2.0.0, and
also it was no longer in development.

There was a fork, m2r2, which had little activity, and would avoid the
security issue by very simply pinning the Mistune version to 0.8.4
(which would either fail to build Cilium's reference correctly, or bring
some incompatibilities with other dependencies, at this point the
narrator does not remember for sure).

There was a fork of the fork, sphinx-mdinclude. We could use that
project to update openapi, except that it was not compatible with recent
versions of docutils, and that this would cause openapi's test suite to
fail to pass.

... So we ended up forking the openapi repository to update the
dependency to sphinx-mdinclude locally, and this is what we've been
using since last summer. And things were good again.

But things are even better when they go upstream [citation needed]. We
also filed the issue for docutils compatibility in sphinx-mdinclude [1].
It was fixed (thanks!). We submitted a PR to have openapi switch to
sphinx-mdinclude [2]. It was adjusted (thanks!), merged, and a new tag
was created.

Now at last, we can switch back to the upstream version of openapi!
[And the build system lived happily ever after.]

[0]: https://github.com/advisories/GHSA-fw3v-x4f2-v673
[1]: https://github.com/omnilib/sphinx-mdinclude/issues/8
[2]: https://github.com/sphinx-contrib/openapi/pull/127

I did _not_ run `make -C Documentation update-requirements`, because the
resulting changes seemed to break the Netlify preview [3]. I stuck to
openapi and bumped sphinx-mdinclude to >= 0.5.2, as required by openapi.

[3] https://app.netlify.com/sites/docs-cilium-io/deploys/63c55fcc5531c6000838b87c

Signed-off-by: Quentin Monnet <quentin@isovalent.com>
1 parent 4ec82bb
History
Tip revision: 3eee19a17a23489bb9461e0526f42d7f71da35ed authored by Quentin Monnet on 16 January 2023, 13:56:21 UTC
docs: Drop sphinxcontrib-openapi fork, switch back to upstream
Tip revision: 3eee19a
File Mode Size
.github
.nvim
.travis
.vscode
Documentation
api
bpf
bugtool
cilium
cilium-health
clustermesh-apiserver
contrib
daemon
envoy
examples
hack
hubble-relay
images
install
jenkinsfiles
operator
pkg
plugins
proxylib
test
tools
vendor
.authors.aux -rw-r--r-- 416 bytes
.clomonitor.yml -rw-r--r-- 984 bytes
.gitattributes -rw-r--r-- 689 bytes
.gitignore -rw-r--r-- 1.7 KB
.golangci.yaml -rw-r--r-- 3.1 KB
.mailmap -rw-r--r-- 5.6 KB
.travis.yml -rw-r--r-- 492 bytes
AUTHORS -rw-r--r-- 34.0 KB
CODEOWNERS -rw-r--r-- 23.2 KB
CODE_OF_CONDUCT.md -rw-r--r-- 2.2 KB
CONTRIBUTING.md -rw-r--r-- 473 bytes
FURTHER_READINGS.rst -rw-r--r-- 6.4 KB
GO_VERSION -rw-r--r-- 7 bytes
LICENSE -rw-r--r-- 11.1 KB
MAINTAINERS.md -rw-r--r-- 4.3 KB
Makefile -rw-r--r-- 30.8 KB
Makefile.defs -rw-r--r-- 7.3 KB
Makefile.docker -rw-r--r-- 6.9 KB
Makefile.quiet -rw-r--r-- 818 bytes
README.rst -rw-r--r-- 17.6 KB
SECURITY.md -rw-r--r-- 629 bytes
USERS.md -rw-r--r-- 24.5 KB
VERSION -rw-r--r-- 8 bytes
Vagrantfile -rw-r--r-- 14.7 KB
go.mod -rw-r--r-- 11.6 KB
go.sum -rw-r--r-- 151.0 KB
netlify.toml -rw-r--r-- 92 bytes
stable.txt -rw-r--r-- 8 bytes
vagrant_box_defaults.rb -rw-r--r-- 394 bytes

README.rst

back to top