Review of actions from last meeting

There were no actions from the previous meeting.

Review of the iteration that has ended

Subplot milestone 35 had the following issued closed:

The following issues remain open:

  • Subplot issue 96 – Error for “do not understand binding” should say in what file the not-understood binding use is found
  • Subplot issue 196 – Python runner stops on first failure
  • Subplot issue 198 – Unify language handling for multi-impl-lang test suites
  • Subplot issue 207 – Release process is too manual, CI build of release .deb changes files
  • Subplot issue 213 – “Failure: document has no title” when there’s duplicate keys
  • Subplot issue 218 – Automatable parts of release process are manual
  • Subplot issue 219 – Needs a release after 0.2.2 to test release automation

We have made reasonable progress. Daniel’s work on multi-language documents is not yet ready for even proofreading, let alone reviewing.

We moved the remaining issues, next milestone (Subplot milestone 36) and then closed off this iteration.

In addition in this iteration now closing we completed some work to enable codegen to use pulldown_cmark instead of pandoc making the dependency chain for generating the test suites lighter. This work was done by Lars primarily, with a little help from Daniel, and was covered in Subplot merge request 213, Subplot merge request 214, and Subplot merge request 216.

Review of the repositories

There is one in-progress MR in the subplot repository

The subplot-container-images and subplot-web repositories do not have MRs or extra branches.

There was a spare branch in subplot called cmark-parser which we removed as it was either an earlier version of the work mentioned above, or else was simply stale. There is also the subplot-rust branch which Daniel is keeping around until he has completed the work on Subplot issue 198.

We triggered the pipeline to build the container image for Subplot. All subplot pipelines are clean.

Current goal (goal 2)

Subplot provides a set of libraries with identical capabilities in each of the supported languages. Python remains a supported language. Rust is promoted to supported-language status. Subplot will be tested with all supported languages. In addition, any quality of life improvements which can be done shall be done. This goal will be considered complete when a release of Subplot has been made with the unified language handling support complete.

Issue review

This time we reviewed only the recently changed open issues, except those tagged someday-maybe. We updated the issues as we reviewed with any new comments or decisions. Notably we made the following changes:

  • Subplot issue 96 – “do not understand binding” error. Lars has updated the issue with a note that the code is a mess around generating this error. At least in one place where we produce the error we don’t then pass it up to the caller, so we need to review what’s going on. We chose to drop this from the milestone, and from the goal, so that it can be tackled when we refactor for better lint/warn/error support.
  • Subplot issue 196 – “python runner stops on first failure”. Lars has a merge request open to fix this issue, so it is in the next iteration.
  • Subplot issue 198 – “language unification”. Daniel explained the current state of the merged support for polyglot bindings, and that he had an abortive attempt at solving the polyglot documents problem but that was abandoned in favour of being able to merge Lars’ work on pulldown_cmark support.
  • Subplot issue 207 – “release process too manual” - we left it as it, assigned to the new milestone.
  • Subplot issue 213 – “failure: document has no title” - Lars had a go at working on this, but he doesn’t want to do the work as proposed (changing pandoc arguments) because long-term we want to move to not using Pandoc to parse the Subplot document itself. As such we’ve demilestoned it, unassigned it from Lars, and added the blocked label.
  • Subplot issue 218 – “automatable release parts are too manual” is carried into our next iteration and left assigned to Lars.
  • Subplot issue 219 – “making a release …” we can’t make this 0.2.2 so we’re going to call it 0.3.0 instead since there’s a breaking change (polyglot bindings) and a breaking change (cmark for codegen).
  • Subplot issue 239 – “in metadata, author is a single string” – this is because in the cmark handler for metadata, the author field must be a single string. Pandoc accepts either a single string or a list of strings, so we should improve our cmark metadata handler to support this too. We assigned this to Lars and put this into the milestone having decided to have a go at trying to support the Pandoc approach by means of an enum.
  • Subplot issue 238 – “doesn’t support abstract in metadata” - we discussed this and Lars has assigned it to himself to have a go at in the new milestone.
  • Subplot issue 236 – “codegen on a document without scenarios should be an error” which was opened by Daniel during the last iteration. We discussed implementation a little, and then assigned it to Daniel and put it into the milestone. We also did some label triage.
  • Subplot issue 235 – “ is too long” - We added active discussion and unhelpful labels along with someday-maybe on the assumption that we will obviously be reviewing all issues before a 1.0 release.
  • Subplot issue 220 – “generated rust test programs are hard to debug” - we will probably want to have a discussion about what should be traced at what level, and ensure that everything coming from subplotlib itself logs that way. Daniel mentioned trying the tracing-test library but that will need some changes before we can use it. We also added actively-discussed.
  • Subplot issue 227 – “workflow for using codegen from” We intend to consider the best workflows and then write stuff up on the issue when we come up with points.
  • Subplot issue 229 – “Licence clarification needed” - We agreed that:
    1. Subplot, Subplotlib, and any python or shell libraries remain under the GPL 3.0.
    2. We add a libgcc style exception clause which permits any code from subplot and associated libraries which ends up linked to or embedded in any test suite to not be infected by the GPL.
    3. This is critical to goal 2.

Plan for next iteration

We opened Subplot milestone 36 to cover this iteration, with the following issues:

Other business

  • Metadata parsing - lax or strict. We discussed during the issue review. Daniel proposed a pandoc: key in the metadata which can contain an arbitrary key/value map to be passed directly to pandoc. We decided to see how complex that might be for now, and if it’s not easy then we will just add more strict support until we are ready to replace the docgen parse pipeline with the cmark pipeline. We agree that it’s important to be strict in what we accept for subplot itself. Early error messages that we are in control of are better for our users. We cannot have a complete list of everything Pandoc can deal with, especially because some of it goes into the latex backend.
  • We discussed the use of subplot in the Sequoia-PGP project and we agreed that we have sufficient issues filed for now. Daniel suggested a label for issues which are blocking high profile projects from adopting Subplot. Lars has taken an action to do this and label up some of the issues.
  • Regarding the media repo, we agreed to hold off for now, but keep the AOB. When we have made a decision to present then we will look again at this.
  • Regarding how we convince others to use Subplot - Daniel explained that he feels that the best way is a combination of demonstrating by means of using Subplot, and then presentations at conferences. Lars feels that he did not communicate well why Subplot is worth using when he tried to present to sq testing. Lars could also write blog posts about using Subplot for Obnam. Once Sequoia or Rustup is using Subplot then we want blog posts on those projects.
  • A useful takeaway is that we need to talk about Subplot more and with a wider variety of potential users, in order that we can collate useful information on how to persuade people of Subplot’s usefulness.
  • We do not know yet about cargo release


  • Lars to create a label for blocking-high-profile-projects (name to be decided by Lars when he does it) and to label at least the Sequoia-PGP blockers if not also anything else he thinks may be blocking projects such as Rustup.