planning meeting minutes

Sponsored-by: author

1 files changed, 166 insertions, 0 deletions

diff --git a/blog/2023/07/planning.mdwn b/blog/2023/07/planning.mdwn
new file mode 100644
index 0000000..9b4b8ed
--- /dev/null
+++ b/blog/2023/07/planning.mdwn
@@ -0,0 +1,166 @@
+[[!meta title="Iteration planning: July 1–15"]]
+[[!meta date="2023-07-01 13:30:00 +0100"]]
+[[!tag meeting]]
+
+[[!toc levels=2]]
+
+[previous meeting]: /blog/2023/06/03/planning
+[subplot-container-images]: https://gitlab.com/subplot/subplot-container-images
+[subplot-web]: https://gitlab.com/subplot/subplot-web
+[subplot]: https://gitlab.com/subplot/subplot
+
+# Assessment of the iteration that has ended
+
+The previous iteration was [[!ms 11]].
+
+There were no actions from the [previous meeting][].
+
+We have made good progress and have nearly finished goal 3. See below
+for what's left.
+
+# Discussion
+
+## 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 will review the billing page every iteration or two.
+
+## Repository review
+
+We reviewed issues (see below) and MRs. We made the decision
+to keep the reference test MR open until the release process during
+the next iteration.
+
+We also checked in on CI pipelines for all the projects in the [Subplot
+group](https://gitlab.com/subplot) on gitlab.com.
+
+| Repository                   | Open issues | Closed issues | Open MRs | Closed MRs |          CI |
+| :--------------------------- | ----------: | ------------: | -------: | ---------: | ----------: |
+| [subplot-container-images][] |           0 |             5 |        0 |          3 | OK (GitLab) |
+| [subplot-web][]              |           0 |             4 |        0 |         86 |    OK (Ick) |
+| [subplot][]                  |          47 |           279 |        0 |        333 | OK (GitLab) |
+
+Extra branches: none.
+
+## 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_
+  - Our plan is to wait until we can do `cargo update` using the Rust
+    toolchain in Debian `testing` without having to adjust any of the
+    dependencies to newer version, before we approach Debian about
+    packaging Subplot.
+  - We hope that an active Debian developer has interest in Subplot,
+    as we neither in position to actively help in maintaining packages
+    in Debian of Subplot and its dependencies. Time will tell if this
+    happens.
+
+## What's remaining for current goal?
+
+We discussed this at some length. We've resolved all but one issue
+labeled for goal 3, but when we reviewed all the issues, we noticed
+things that may cause breaking changes if we change them later. We'd
+like to do all such breakage in goal 3. The things we noticed are:
+
+- [[!subplotissue 326]] Decide what to do about bibliography data__
+  - we already don't use the bibliography stuff, but we allow it in
+    document metadata, so the change we need to do is to stop allowing
+    bibliography information in metadata
+  - not even allowing the metadata to refer to bibliography
+    information is a breaking change
+- [[!subplotissue 261]] _Cleanup functions should run regardless of
+  whether or not their step function succeeded_
+  - we decided to document that step functions must be atomic: either
+    they succeed (and will be cleaned up later by the cleanup
+    function), or they fail and leave nothing to be cleaned up
+  - this is a breaking change as such, but we want to make the
+    expectation clear
+- [[!subplotissue 329]] _Doesn't document that scenario block
+  attributes are reserved_
+  - A markdown document can add nearly arbitrary attributes to a
+    scenario block. In order to avoid breaking changes, when Subplot
+    adds meaning to such attributes, we need to reserve the name space
+    of attributes for Subplot. This needs to be documented.
+  - Doing that will enable to to, for example, have labels on
+    scenarios, [[!subplotissue 228]].
+
+# 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. It will need to be discussed in
+depth when we finish the previous goal.
+
+We'll improve the quality of life of people using Subplot:
+
+* we'll improve the ease of use and comprehension of the output of
+  documents generated by Subplot
+* we'll improve the documentation of Subplot itself
+* we'll make error messages and other diagnostics more helpful for
+  users to fix whatever the problem is
+
+We aim to have a fairly short and time-boxed goal 4, maybe on the
+order of two or three months. The goal 3 duration (well over a year)
+was long enough to be de-motivating to use as developers. Thus, we
+scope our actual tasks so that they are likely to be achieved by us,
+given our time and energy constraints. We'd rather have more frequent
+small goals than more ambitious goals that take a long time to
+achieve.
+
+([Related issues on gitlab](https://gitlab.com/subplot/subplot/-/issues?label_name%5B%5D=goal%3A%3A4))
+
+# Plan for new iteration
+
+## Issues
+
+We did an issue review for all issues to try to avoid breaking changes
+in the near future. As part of that, we commented on some issues,
+adjusted some issue labels, created a couple of new ones.
+
+We created [[!ms 12]] with the following issues:
+
+- [[!subplotissue 261]] _Cleanup functions should run regardless of
+  whether or not their step function succeeded_
+  - Lars will document that step functions need to be atomic
+- [[!subplotissue 305]] _Maybe create binary releases?_
+  - Daniel will give this a try
+- [[!subplotissue 326]] _Decide what to do about bibliography data_
+  - Lars will drop support for bibliographies in document metadata
+- [[!subplotissue 328]] _Promote location information into
+  Scenario/ScenarioStep_
+  - Daniel will implement this
+- [[!subplotissue 329]] _Doesn't document that scenario block
+  attributes are reserved_
+  - Lars will document this
+
+After these are all done, we have finished goal 3.
+
+## Actions
+
+No additional actions.
+
+# Meeting participants
+
+- Daniel Silverstone
+- Lars Wirzenius