Skip to content

Commit

Permalink
Add CONTRIBUTING.md to help new contributors with UI testing issues
Browse files Browse the repository at this point in the history
  • Loading branch information
hartwork committed Nov 26, 2023
1 parent 0747ea6 commit a187c2e
Showing 1 changed file with 53 additions and 0 deletions.
53 changes: 53 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
# Welcome to ttyplot!

This file documents how to contribute to ttyplot and
things to know before facing them. It will likely
never be complete, but if tomsehing important
turns out to be missing here, let's add it.


## Problem: The CI complains that two images are too dissimilar

The CI does basic UI testing by making screenshots
of the running application and comparing them
against screenshots `recordings/expected-*.png`.
When you make changes that change the the appearance of
ttyplot, the CI will hopefully catch thes changes
and reject them as a regression. In a case where these
changes are made with full intention, the images
that the CI is comparing against at
`recordings/expected-*.png` will need to be regenerated.
For your convenience, an easy way to do that is:

```console
$ ./recordings/get_back_in_sync.sh
```

For that to work well on macOS, you would need to install:

```console
$ brew tap homebrew/cask-fonts
$ brew install \
agg \
asciinema \
coreutils \
font-liberation
```

For that to work well on Debian-based Linux, you would need to install…

```console
$ sudo apt-get update
$ sudo apt-get install --no-install-recommends -V \
asciinema \
ca-certificates \
cargo \
fonts-liberation
$ cargo install --git https://github.com/asciinema/agg
```

…and put the install location of `agg` into `${PATH}`:

```console
$ export PATH="${PATH}:${HOME}/.cargo/bin"
```

0 comments on commit a187c2e

Please sign in to comment.