summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLars Wirzenius <liw@liw.fi>2022-07-16 13:20:57 +0300
committerLars Wirzenius <liw@liw.fi>2022-07-17 11:35:46 +0300
commit9e817b40ba8ea2e4ca049f9f3730e69b495b560c (patch)
treeb6c90f382bae26f697a671f71ac9afe434eb7908
parent30cb87b2fc52a433d734769bc5052ca8f862b2d1 (diff)
downloadsubplot.liw.fi-9e817b40ba8ea2e4ca049f9f3730e69b495b560c.tar.gz
add minutes for yesterday's iteration planning meeting
Sponsored-by: author
-rw-r--r--blog/2022/07/16/planning.mdwn266
1 files changed, 266 insertions, 0 deletions
diff --git a/blog/2022/07/16/planning.mdwn b/blog/2022/07/16/planning.mdwn
new file mode 100644
index 0000000..8591f03
--- /dev/null
+++ b/blog/2022/07/16/planning.mdwn
@@ -0,0 +1,266 @@
+[[!meta title="Iteration planning: July 16 &ndash; 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