Skip to content

GitLab

  • Menu
Projects Groups Snippets
    • Loading...
  • Help
    • Help
    • Support
    • Community forum
    • Submit feedback
    • Contribute to GitLab
  • Sign in / Register
  • BIND BIND
  • Project information
    • Project information
    • Activity
    • Labels
    • Planning hierarchy
    • Members
  • Repository
    • Repository
    • Files
    • Commits
    • Branches
    • Tags
    • Contributors
    • Graph
    • Compare
  • Issues 527
    • Issues 527
    • List
    • Boards
    • Service Desk
    • Milestones
  • Merge requests 101
    • Merge requests 101
  • CI/CD
    • CI/CD
    • Pipelines
    • Jobs
    • Schedules
  • Deployments
    • Deployments
    • Environments
    • Releases
  • Monitor
    • Monitor
    • Incidents
  • Packages & Registries
    • Packages & Registries
    • Container Registry
  • Analytics
    • Analytics
    • Value stream
    • CI/CD
    • Repository
  • Wiki
    • Wiki
  • Snippets
    • Snippets
  • Activity
  • Graph
  • Create a new issue
  • Jobs
  • Commits
  • Issue Boards
Collapse sidebar
  • ISC Open Source Projects
  • BINDBIND
  • Issues
  • #2448

Closed
Open
Created Jan 29, 2021 by Michał Kępień@michalOwner

Sphinx-generated documentation built in GitLab CI is sometimes defective

@pspacek noticed that the latest PDF version of the BIND 9 ARM is missing the entire "BIND 9 Configuration Reference" chapter:

https://ftp.isc.org/isc/bind9/9.17.9/doc/arm/Bv9ARM.pdf

The same problem seems to be affecting the PDF for 9.17.8:

https://ftp.isc.org/isc/bind9/9.17.8/doc/arm/Bv9ARM.pdf

but not for 9.17.7:

https://ftp.isc.org/isc/bind9/9.17.7/doc/arm/Bv9ARM.pdf

None of the 9.16.x PDFs seem to be broken this way.

I could not reproduce this problem locally and also confirmed there were no changes in the doc/ directory between 9.17.7 and 9.17.8 that could have caused this. Upon further investigation, I discovered that the problem is caused by using parallel make jobs (-j) when running make doc in GitLab CI - this causes multiple sphinx-build instances to run simultaneously in the same working directory, which means they can stomp on each other's data. Unfortunately, problems like this only triggered Sphinx warnings, not errors, so the relevant GitLab CI jobs have been silently passing.

This conclusion means that all forms of our documentation might have been malformed in one way or another ever since we migrated to Sphinx, i.e. since May 2020 (see !1761 (merged), !3536 (merged)). Looking at GitLab CI job traces from the past 2 months, it can be estimated that the problem has a roughly 15% chance of getting triggered for any Sphinx documentation build job. (See correction below.)

Edited Feb 03, 2021 by Michał Kępień
Assignee
Assign to
Time tracking