Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Make transcripts idempotent #5406

Merged
merged 17 commits into from
Nov 26, 2024
Merged

Commits on Oct 9, 2024

  1. Make transcript output valid Markdown

    All serialization is now down via CMark (previously, all `api` and `ucm` blocks in the output were still being
    serialized directly, because of the interleaving of the input text and command/request output).
    
    This causes a few changes to the existing transcript outputs:
    - there is now always a blank line between Markdown block elements,
    - leading blank lines in UCM blocks are gone,
    - blank lines at the end of transcripts are gone (they still end with a final POSIX newline), and
    - some `ucm` blocks now have 4-backtick fences (because they contain triple-backticks).
    
    Transcript failures are now also handled as Markdown, rather than just being text appended to the document. This mostly
    doesn’t change the serialization, except that the failure message is now fenced, since they often contain newlines and
    indentation that is mangled otherwise.
    sellout committed Oct 9, 2024
    Configuration menu
    Copy the full SHA
    92721fd View commit details
    Browse the repository at this point in the history
  2. Configuration menu
    Copy the full SHA
    0735fb3 View commit details
    Browse the repository at this point in the history
  3. Some transcript info tag improvements

    This includes changes that get us closer to running transcript outputs as inputs
    - all `ProcessedBlock`s (`api`, `ucm`, and `unison`) now handle info tags the same way – previously `ucm` didn’t allow
    spaces between tags like `:hide :error`, and `api` didn’t support info tags at all.
    - preserve info tags in the output – `ucm :error` in the input results in `ucm :error` in the output
    - parser now supports `:added-by-unison` (only useful for parsing outputs as inputs)
    sellout committed Oct 9, 2024
    Configuration menu
    Copy the full SHA
    f41c78d View commit details
    Browse the repository at this point in the history

Commits on Oct 10, 2024

  1. Toward idempotent transcripts

    - fix `:hide` on `ucm` and `api` blocks – previously it behaved the same as `:hide:all`, which prevents the outputs being used
    as transcripts
    - include `:added-by-ucm` to `ucm` blocks inserted after `unison` blocks
    - ensure output lines have 2-space indents
    
    This adds a couple transcripts testing the `:hide` behavior.
    sellout committed Oct 10, 2024
    Configuration menu
    Copy the full SHA
    c84495f View commit details
    Browse the repository at this point in the history
  2. Configuration menu
    Copy the full SHA
    39e51b6 View commit details
    Browse the repository at this point in the history
  3. Make transcripts idempotent

    This provides the final pieces to make transcripts idempotent enough
    that we can use transcript outputs as inputs.
    
    This simplifies bug reporting, as now the GitHub issue can be written
    _as_ a transcript, even if you want to include some of the output in the
    bug report. No need to wrap the entire transcript in ` ```` markdown`.
    
    The parser changes here also improve error messages in some existing cases.
    
    There are some caveats:
    - failing transcripts are not _yet_ idempotent. There are issues with how errors are reported (especially parse
    failures) that make them not round-trip
    - `:hide:all` almost always breaks idempotency. This is intentional – to just hide the output, use `:hide` instead.
    sellout committed Oct 10, 2024
    Configuration menu
    Copy the full SHA
    a22f9a3 View commit details
    Browse the repository at this point in the history
  4. Configuration menu
    Copy the full SHA
    cf0f3e2 View commit details
    Browse the repository at this point in the history
  5. Inline scratch files in transcripts

    These were previously separated because transcripts previously couldn’t contain code blocks with triple backticks, but that is fixed now.
    sellout committed Oct 10, 2024
    Configuration menu
    Copy the full SHA
    041d0f4 View commit details
    Browse the repository at this point in the history
  6. Run idempotent transcript tests

    This produces the first output files, which should remain unchanged on
    subsequent runs.
    sellout committed Oct 10, 2024
    Configuration menu
    Copy the full SHA
    73b2a9c View commit details
    Browse the repository at this point in the history
  7. Hide output on a few transcripts

    Idempotent transcripts can get large, so using `:hide` more liberally is
    probably a good idea. This tries that out on a few transcripts.
    sellout committed Oct 10, 2024
    Configuration menu
    Copy the full SHA
    e6632a5 View commit details
    Browse the repository at this point in the history

Commits on Nov 11, 2024

  1. Add verification for non-test transcripts

    Checks that other transcripts in the source tree (currently just the GitHub
    bug-report template) are valid.
    
    This also fixes a bug where a transcript block like ` ``` ucm :hidec`
    would be parsed like ` ``` ucm :hide c`, rather than complaining that
    there is no `hidec` tag.
    
    This currently fails because of a typo introduced earlier in this PR.
    sellout committed Nov 11, 2024
    Configuration menu
    Copy the full SHA
    ade889f View commit details
    Browse the repository at this point in the history
  2. Fix typo in bug_report template

    This is caught by a test introduced in the previous commit.
    sellout committed Nov 11, 2024
    Configuration menu
    Copy the full SHA
    bff98d3 View commit details
    Browse the repository at this point in the history
  3. Configuration menu
    Copy the full SHA
    bc93be5 View commit details
    Browse the repository at this point in the history
  4. Update interpreter test output

    This also makes a couple minor changes re: running the script:
    
    - removes the “belt and suspenders” `echo`ing that resulted in things being printed in triplicate
    - added `gettext` to the Nix environment,  so `envsubst` is available
    - changed the #!, to not get stuck with Bash 3.2 on macOS.
    sellout committed Nov 11, 2024
    Configuration menu
    Copy the full SHA
    2673620 View commit details
    Browse the repository at this point in the history

Commits on Nov 12, 2024

  1. Configuration menu
    Copy the full SHA
    911c799 View commit details
    Browse the repository at this point in the history

Commits on Nov 26, 2024

  1. More precise blank lines in transcript UCM blocks

    This avoids leading and trailing blanks, while ensuring they exist between commands & outputs.
    sellout committed Nov 26, 2024
    Configuration menu
    Copy the full SHA
    b7edcd6 View commit details
    Browse the repository at this point in the history
  2. Configuration menu
    Copy the full SHA
    7e26050 View commit details
    Browse the repository at this point in the history