diff options
Diffstat (limited to 'talk.md')
-rw-r--r-- | talk.md | 109 |
1 files changed, 87 insertions, 22 deletions
@@ -4,21 +4,33 @@ author: Lars Wirzenius for the Subplot project date: 2019-10-10 ... - https://subplot.liw.fi/ +Subplot is a set of tools for **specifying** and **documenting** +acceptance criteria for a system or project, and how they should be +**verified**. + +**All stakeholders**, including customers and end-users, should +understand these. +It's not easy. Subplot can't do it alone. You still have to write text +that +everyone understands. + + https://subplot.liw.fi/ --- -Subplot? Let me tell you a story... +Once upon a time there was a king... --- -![](arch.svg) +It all started with yarn in 2013 --- Acceptance criteria are expressed as scenarios (a la Cucumber): + + _given_ a system in a specific start state _when_ user does some thing _then_ system state has changed in the intended way @@ -26,21 +38,33 @@ _and_ other aspect of state has stayed the same --- -FIXME: Markdown example - +~~~~markdown --- +title: "**echo**(1) acceptance tests" +... +# Introduction +**echo**(1) is a Unix command line tool, which writes +its command line arguments to the standard output. +This is a simple acceptance test suite for the +`/bin/echo` implementation. + +# No arguments +Run `/bin/echo` without arguments. +```fable +when user runs echo without arguments +then exit code is 0 +and standard output contains a newline +and standard error is empty +``` +~~~~ -Currently only docgen exists, codegen will happen soon. - -Docgen = Pandoc + Pandoc filter, in Rust +--- -Filter modifies document during typesetting to make document more -useful for communicating acceptance criteria. Changes how code blocks -with scenario text are presented. +![](echo.png) --- -FIXME: Bindings example +![](arch.svg) --- @@ -53,6 +77,48 @@ Essentially, scenario step is a function call. --- +~~~~yaml +- when: user runs echo without arguments + function: run_echo_without_args + +- when: user runs echo with arguments (?P<args>.+) + function: run_echo_with_args + +- then: exit code is (?P<exit_code>\d+) + function: exit_code_is_zero + +- then: standard output contains a newline + function: stdout_is_a_newline + +- then: standard output contains "(?P<text>.*)" + function: stdout_is_text + +- then: standard error is empty + function: stderr_is_empty +~~~~ + +--- + +Currently only **docgen** exists, work on **codegen** will start soon. + + + +> docgen = Pandoc + Pandoc filter, in Rust + + + +Filter modifies document during typesetting to make +document more useful for communicating acceptance +criteria. Typesets scenario text, later maybe other +things. + +Relies on the `pandoc` and `pandoc_ast` crates for +typesetting, `structopt` for command line handling + +Really quite simple + +--- + ~~~~rust use std::path::PathBuf; use structopt::StructOpt; @@ -177,8 +243,7 @@ fn typeset_str(s: &str) -> Inline { --- -The Subplot project is at the very beginning (but Yarn was used for -six years). Help is welcome. +The Subplot project is at the very beginning. Help is welcome. * What do you think of the concept? * What's good? @@ -186,22 +251,22 @@ six years). Help is welcome. * Can you see yourself using it? * What would it take for you to try it? * Do you see Subplot filling a gap for you? +* Can you help with improvements to website, documentation, code? +* Would you be willing to try Subplot in your project? -Expect a working version by the end of the year. Patches are welcome, -but more important now is constructive feedback, especially from -people who use Subplot, or want to. +Expect a working, but primitive version by the end of the year. Patches are welcome, +but more important right now is constructive feedback, especially from +people who use Subplot, or might want to. --- -Free software. +Free software. GPL3+ -Won't affect the licensing of the outputs. OK to use for proprietary -systmes. +Won't affect the licensing of the outputs. OK to use for developing proprietary +systems, but Subplot itself will remain free. --- Thank you ---- - This talk is licensed CC-BY-SA 4.0 (International) |