NEWS.md 9.06 KB
Newer Older
1
# Release notes for Subplot
2
3

This file summarises the changes between released versions of Subplot and its
4
5
6
associated libraries, especially with regards to changes visible to
the user of the Subplot software.

7
8
9
10
11
# Version 0.4.1 (subplotlib only), released 2022-04-17

- Fix issue where subplotlib cannot be built out-of-tree

# Version 0.4.0, released 2022-04-16
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

- The largest change from the previous release is that Rust based
  subplot scenario test suites are now considered supported.
  You can find an example of this in the `examples/seq` project in
  the Subplot source code.

- To achieve this, bindings are now "polyglot" in the sense that they
  are not language specific, though some bindings may only provide
  implementations for particular languages (e.g. the daemon bindings
  currently only support Python)

- Subplot considers Rust 1.48.0 to be its MSRV. This is to enable
  integration into certain distributions and to work with other projects
  whose MSRVs are around that value.

- A number of quality of life improvements around warning delivery,
  template handling, etc. have been made. For the full details, see
  the Git changelog.

31
32
# Version 0.3.1, released 2021-11-16

33
- The primary purpose of this release is to make the `PATH` bug fix
34
35
36
37
  available via crates.io, to fix use of Subplot in the Sequoia-PGP
  project. There are no breaking changes, so only the patch level of
  the version number is incremented.

38
- The licence of Subplot has been changed to
39
40
41
42
43
44
45
46
47
48
  [MIT-0](https://mit-license.org/), to make it as simple as possible
  to use Subplot on other projects, without having to worry about
  license compatibility. Previously, this was technically possible,
  but the Subplot licence situation was complex enough that it caused
  people ask questions.

  The Subplot developers prefer, for Subplot, to maximize adoption and
  though they would favor a copyleft licence otherwise, they're
  willing to compromise this time.

49
- A bug has been fixed in the Rust `lib/runcmd` function
50
51
52
53
  implementation to prepend a directory to the `PATH`, in the
  `subplotlib::steplibrary::runcmd::try_to_run_in` function. The bug
  meant that the directories in `PATH` ended up in the wrong order.

54
55
56
57
58
59
60
61
# Version 0.3.0, released 2021-10-20

This is still an ALPHA quality release, and includes breaking changes.

## Breaking changes

You definitely need to pay attention to these changes.

62
- Subplot is moving to libraries and subplots being able to support
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
  multiple step implementation languages at once. In this release,
  bindings can indicate different functions for each language. Note
  that a binding only needs to support one language. The new binding
  format is:

```yaml
- given: foo
  impl:
    python:
      function: foo
      cleanup: foo_cleanup
    rust:
      function: somelib::foo
      cleanup: somelib::foo_cleanup
```

79
- The Subplot code generator now uses the `pulldown-cmark` crate for
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
  parsing Markdown input. The reason for this change is to not have to
  have Pandoc installed in a CI or other environment that only
  generates and runs test programs.

  The document generator still uses Pandoc for this, but it, too, will
  migrate to `pulldown-cmark` so that all parsing is done in the same
  way.

  The parsing crate should support the same Markdown variants as
  Pandoc does, more or less.

  Unfortunately, the YAML document metadata block is less forgiving
  now. The new metadata parser doesn't accept everything Pandoc does,
  and there will be a need to change input documents. The next release
  of Subplot is likely to introduce further changes, and we will
  document the new metadata format then.

97
- The generated test programs no longer clear the environment
98
99
100
101
102
103
104
105
106
  variables before running scenarios. This is partly to allow Subplot
  to be more easily ported to operating systems other than Debian
  (such as NixOS, but also Windows and macOS), but also because
  clearing the environment variables is not a good way to make sure
  the tests run in a known environment. Subplot now makes it the
  responsibility of the person running the test program to control
  where it is run: what software is installed, what services are
  available, etc.

107
- Subplot code generation now refuses documents that have no
108
109
110
111
112
113
114
115
116
117
  scenarios. Document generation still accepts them so that Subplot
  can be used to produce typeset documents and web pages.

## General

The changes in this section should not break any existing Subplot
documents. They affect all uses of Subplot, regardless of step
implementation language and whether Subplot code or document
generation is used.

118
- After a bug fix, Subplot now handles better the input files being
119
120
121
122
123
  elsewhere than the current directory. If the Markdown input file is
  in `foo/bar/yo.md`, the files referred to from the input file are
  looked up relative to `foo/bar` instead of the current working
  directory.

124
- Subplot now has initial support for logging to make it easier to
125
126
127
128
129
130
  find out what it's doing, when it's doing something surprising. The
  environment variables `SUBPLOT_LOG`, `SUBPLOT_LOG_FILE`, and
  `SUBPLOT_LOG_FORMAT` (`oneline`, `json`, or `pretty`). What Subplot
  logs is still rudimentary but will be improved over time. We'd
  welcome suggestions.

131
- The Subplot Debian package now builds in the resource into the
132
133
  Subplot binary.

134
- Document titles can now use markup to indicate `literal` text.
135

136
- Subplot now automatically handles versions of Pandoc that don't have
137
138
139
  a separate `pandoc-citeproc` binary, and want the `--citeproc`
  option instead.

140
- Subplot now works with version 1.48.0 of the Rust language and
141
142
143
144
145
  toolchain, in order to make it possible for the Sequoia-PGP project
  to use Subplot.

## Python support

146
- The generated Python test program now supports the `--run-all`
147
148
149
150
  (`-k`) option to run all scenarios even if one or more fail.

## Rust support

151
- Subplot now provides the `subplot-build` crate, for using Subplot
152
153
  code generation from another project's `build.rs` script.

154
- We are in the process of elevating Rust into a supported language,
155
156
157
158
159
  so that it will be on par with Python. This release does not get
  there, but starts the process.

## Bash support

160
- We've not made much effort to improve the Bash support (modulo the
161
162
  environment cleanup). Compared to Python and Rust it is not a
  well-support language in Subplot. Lars and Daniel do not feel it is
xipmix's avatar
typo    
xipmix committed
163
  a target worth spending much of their free time on, but would
164
165
  welcome help with that.

166
167
168
169
170
171
172
173
174
# Version 0.2.2, released 2021-08-07

This is release is meant for use by people other than Subplot's own
developers. It is of ALPHA quality, in that what is implemented is
meant to work, but we reserve the right to make backwards incompatible,
breaking changes in future releases.

## General

175
- When a scenario step matches more than one binding, the error
176
177
178
  message now lists all the matching bindings to make it easier for
  the user to fix the problem. (By Lars Wirzenius)

179
- The documentation now explains core concepts relevant to Subplot,
180
181
182
183
184
  and suggests an initial workflow for a project using Subplot. (By
  Lars Wirzenius)

## Python support

185
- The `lib/daemon` Subplot library now uses custom Python code instead
186
187
188
189
  of the netcat tool. This removes a dependency, and also avoids the
  problem of there being at least two more or less incompatible
  versions of netcat in common use. (By Alexander Batischev)

190
- The `lib/daemon` library now has a way to pass environment variables
191
192
193
194
  to the daemon. (By Alexander Batischev)

## Bash support

195
- The documentation now makes it clearer that the `files_get`
196
197
  function returns the contents of the embedded file and not a
  filename. (By Richard Maw)
198

199
- Some spelling and other language mistakes have been fixed in the
200
201
  documentation for Bash support. (By Richard Maw)

202
- The `dict` helper functions can now read embedded files. (By Richard
203
204
  Maw)

205
- The generated Bash test program now supports the `--env` option to
206
207
  let the user pass in environment variables when invoking the test
  program. (By Richard Maw)
208

209
- Assertion functions now return an error rather then terminating the
210
211
  test program. This lets cleanups run. (By Richard Maw)

212
213
214
215
216
# Version 0.2.1, released 2021-07-11

This is the first release meant for use by people other than Subplot's
own developers.

217
- The locations of the `dot` and `plantuml` programs and for the Java
218
219
220
221
222
  byte code interpreter can now be configured when Subplot is invoked,
  which is useful when they're not installed in the locations where
  Debian puts them. Those programs are used by Subplot to render
  diagrams.

223
- The `./check` script now outputs the last one hundred lines or so of
224
225
226
  the log file produced by the generated test program, if that program
  fails. This makes it easier to debug failures under CI.

227
- Additionally, there have been some minor tweaks only visible to
228
229
  those developing Subplot itself.

230
231
232
233
234
235
236
237
# Version 0.2.0, released 2021-06-12

This is the first public release of Subplot. No APIs or other surfaces are to be
considered stable at this time. While the `subplotlib` and `subplotlib-derive`
crates have been published, they do not form part of this release.

The only _template_ which is considered in any sense "supported" in this release
is the `python` template.