path: root/blog/2022/07/16/planning.mdwn

[[!meta title="Iteration planning: July 16 – 30"]]
[[!meta date="Sat, 16 Jul 2022 15:30:00 +0300"]]
[[!tag meeting]]

[[!toc levels=2]]

# Actions from last time

* DONE: Lars will reach out to Hillel Wayne once more during this iteration.
  - Lars emailed, we got a response, to be discussed in this meeting.


# Assessment of the iteration that has ended

We extended, by mutual agreement on Matrix, to extend this iteration
by two weeks. We're both a little short on time and energy for
Subplot, lately.

We had chosen the following issues for this iteration:

- [[!webissue 3]] -- _Document how we do meetings_
  - assigned to Daniel
- [[!subplotissue 283]] -- _YAML metadata is not in its own file_
  - assigned to Lars
- [[!subplotissue 286]] -- _Tests sometimes fail_
  - assigned to Lars

Unfortunately, despite the extension, we didn't make much progress on
these issues. Rather than extend the iteration again, we're having a
meeting.

We decided to extend the iteration again, by another two weeks, rather
than close this iteration and create a new one with the same issues.

# Discussion

## Subplot development speed

We discussed whether the slow development speed should worry us, and
what we can do to make at least some concrete progress each iteration.

We decided that we don't need to worry, as such, but that there are
things we can do to make sure some progress is made in each iteration.
Most importantly, we should include at least some tasks that are small
enough and that we understand well and are enthusiastic about. We
tentatively set the limit on the estimated effort to one hour. Tasks
bigger than that should have at least one sub-task carved out that's
smaller.

## Release to benefit Sequoia?

We discussed making a release of Subplot to help the Sequoia project.
It would mean Subplot doesn't depend on the `clap` version 2 anymore,
and that would help Sequoia reduce its dependency tree and build
times.

There have been nothing very breaking since the previous release. We
decided to make a release soon, and call it 0.4.2. We created
[[!subplotissue 289]] to track this, and assigned it to Lars.

## On YAML metadata

Lars has attempted to unify the two document metadata representations
we have, but feels there's too much entanglement with the older one to
allow for an easy refactoring. This is the [[!subplotissue 283]] issue.

He now feels a better approach may be to convert `docgen` into using
the `pulldown-cmark` parser for Markdown instead, and has made some
progress on that. The current problem is that the rudimentary code to
build a Pandoc AST from `pulldown-cmark` parsing events is meant only
for `codegen`, and is highly insufficient for `docgen`.

We discussed whether to use the Pandoc Abstract Syntax Tree
representation, replace that with an HTML abstraction, or work on the
`pulldocn-cmark` parsing event stream directly. Lars will experiment.
Daniel noted that the event stream can contain source information,
which might make the marked-markdown work unnecessary.

## Feedback from Hillel Wayne

We got feedback from Hillel Wayne, who is a well-known authority on
formal methods for software correctness. He made good points. Our
takeaways:

* Our website and other documentation needs to be more oriented
  towards those not involved in developing Subplot.
  - we can achieve part of this by re-arranging existing content
  - we could write new content, such as a "Subplot book", a la similar
    documentation efforts for Rustup, Cargo, BuildStream, and other
    projects
* Our presentation of what Subplot is needs clarification. Subplot is
  tooling around Gherkin, or a variant of it, but we may not actually
  say that or say it clearly.
* We do think it's possible to write acceptance tests in Gherkin. We
  should expand on what we understand acceptance testing to be.
* We should improve our examples. The current ones are rather
  simplistic. We should add explanatory text to the examples to make
  it clearer what the purpose of each example is.
* We should write documentation to describe how we expect Subplot to
  be used, when used well: who should write subplot documents, who
  should consume them, how they should be written to be good, how to
  design scenario steps, etc.
  - we should also discuss the layered approach described by Daniel in
    his FOSDEM'22 talk about using Subplot for safety

Daniel will draft a response and Lars will review it.

## The gitlab.com hosting situation

We reviewed [the billing
page](https://gitlab.com/groups/subplot/-/billings) for Subplot on
gitlab.com. It all looks OK. We're over the limit on seats, but it
seems we can increase the seats for free.

We will review the billing page every iteration or two.

## Packaging and dependencies

We discussed what we can do to make Subplot easier for other projects
to use Subplot, or to package Subplot, especially for Linux
distributions like Debian.

When other projects use Subplot, it shouldn't require pulling in a
large set of dependencies, whether they are other tools such as Pandoc
and LaTeX, or Rust crates. The bigger the set of unavoidable
dependencies is, the more costly it is to use Subplot, in terms of
computing resources, and maintenance time and effort in the long run.

Debian aims to be self-contained: to build everything in Debian may
only require software packaged in Debian and must not require
downloading anything from the Internet, outside the Debian package
archive. This helps Debian be more stable, less vulnerable to changes
in tens of thousands of other projects. The more dependencies Subplot
has, the more work it is to package.

We should thus keep the dependency tree of Subplot small, when we can
do so with acceptable sacrifices on our part.

* Each Subplot crate is aimed at a different use case. We should
  ensure it dependency tree doesn't accidentally pull in unnecessary
  crates, or extra versions of crates.
* We should aim to keep crate dependencies for building, developing,
  and testing as tidy as possible. Additionally, we should investigate
  how we can tidy up dependencies that are only needed for producing
  binaries, rather than using a crate as a library.

## Repository review

We reviewed issues updated since the previous
meeting, merge requests, and CI pipelines for all the projects in the
[Subplot group](https://gitlab.com/subplot) on gitlab.com.

### [Subplot Container Images](https://gitlab.com/subplot/subplot-container-images)

* Open issues: 1
* Merge requests: 0
* Additional branches: 0
* CI: OK, ran on Friday

### [subplot-web](https://gitlab.com/subplot/subplot-web)

* Open issues: 2
* Merge requests: 1
* Additional branches: 0
* CI: Ick, OK.

### [subplot](https://gitlab.com/subplot/subplot)

* Open issues: 48, newly changed ones reviewed
  - [[!subplotissue 287]] -- _Needs documentation for Rust step
    functions for implementing contexts_
    - assigned to Daniel
  - [[!subplotissue 288]] -- _Should an on-disk filename be captured1
    as a Path?_
    - added to current goal
  - [[!subplotissue 289]] -- _Make release 0.4.2_
    - assigned to Lars
* Merge requests: 1
* Additional branches:
  - `docgen-cmark`, Lars is keeping this around for reference for
    future changes
* CI: OK

## Recurring items issues

There are some issues tagged
[`recurring-agenda-item`](https://gitlab.com/groups/subplot/-/issues/?sort=created_asc&state=opened&label_name%5B%5D=recurring-agenda-item&first_page_size=20)
in the issue tracker, which we discuss in every iteration meeting.

* [[!subplotissue 119]] -- _Subplot is in not in Debian unstable_
  - we will work on reducing Subplot dependencies that aren't already
    in Debian
* [[!subplotissue 272]] -- _Migrate project to issue-based iteration
  meetings_
  - we will try a "merge request based approach" instead, for a few
    iterations
  - Lars has tried this in the Obnam project and it has worked OK
* [[!subplotissue 273[[ -- _Perform whole-codebase review and cleanup_
  - we are not up to doing this yet

# Goals

## Goal 3: Current goal

Subplot is altered to treat a YAML document as the root of any subplot
document, permitting multiple markdown files to be joined into a
single scenario set or output document. We remove our dependency on
Pandoc’s AST for internal document representation, and support a
better range of document metadata as a result. We will use marked data
types where possible to permit better provenance information in error
and warning messages; and we will strive to reenable the reference
tests such that we can make a statement to the effect that post goal
3, we do not intend to make further breaking changes to the input
formats or primary behaviours of Subplot.

([Related issues on gitlab](https://gitlab.com/subplot/subplot/-/issues?label_name%5B%5D=goal%3A%3A3))

## Goal 4: Planned

This goal is very likely to change. This is merely an initial sketch.

We'll improve documentation and generally aim at making Subplot more
plausibly usable by people outside of the Subplot project.

([Related issues on gitlab](https://gitlab.com/subplot/subplot/-/issues?label_name%5B%5D=goal%3A%3A4))


# Plan for new iteration

We intend to work on the following issues:

* [[!webissue 3]] -- _Document how we do meetings_
  - assigned to Daniel
* [[!webissue 4]] -- _Review FAQ_
  - assigned to Daniel, Lars will help as needed
- [[!subplotissue 283]] -- _YAML metadata is not in its own file_
  - assigned to Lars
* [[!subplotissue 286]] -- _Tests sometimes fail_
  - assigned to Lars
  - we've only seen this fail on Lars's Ick CI
  - Lars will try running the build many times to get an idea of how
    often the tests fail
* [[!subplotissue 287]] -- _Needs documentation for Rust step
  functions for implementing contexts_
  - assigned to Daniel
* [[!subplotissue 289]] -- _Make release 0.4.2_
  - assigned to Lars




## Actions

These are in addition to work on issues chosen for this iteration.

* Daniel to draft a response to Hillel Wayne. Lars will review.
* Daniel to research how to have dependencies only for binaries
  produced by a crate, but not the library part of the crate.
* Lars to upgrade his `roadmap` crate to use `clap` version 3, instead
  of `structopt`.


# Meeting participants

* Daniel Silverstone
* Lars Wirzenius