Prep for v0.19.0

[Enselic]

Release checklist

Dependencies

See this page for a good overview: https://deps.rs/repo/github/sharkdp/bat

• Optional: update dependencies with cargo update. This is also done by
  dependabot, so it is not strictly necessary.
• Install cargo-outdated. Check
  for outdated dependencies with cargo outdated --root-deps-only and
  decide for each of them whether we want to (manually) upgrade. This will
  require changes to Cargo.toml.

% cargo outdated --root-deps-only 
Name  Project  Compat  Latest  Kind    Platform
----  -------  ------  ------  ----    --------
clap  2.34.0   ---     3.0.5   Normal  ---

Version bump

• Update version in Cargo.toml. Run cargo build to update Cargo.lock.
  Make sure to git add the Cargo.lock changes as well.
• Find the current min. supported Rust version by running
  grep '^\s*MIN_SUPPORTED_RUST_VERSION' .github/workflows/CICD.yml.
• Update the version and the min. supported Rust version in README.md and
  doc/README-*.md. Check with git grep -i 'rust.*1\.' and
  git grep -i '1\..*rust'.
• Update CHANGELOG.md. Introduce a section for the new release.

Update syntaxes and themes (build assets)

• Install the latest master version (cargo install -f --path .) and make
  sure that it is available on the PATH (bat --version should show the
  new version).

% bat --version
bat 0.19.0 (c378c73)

• Run assets/create.sh and check in the binary asset files.

Documentation

• Review the -h and --help texts

% bat -h
bat 0.19.0 (c378c73)
A cat(1) clone with syntax highlighting and Git integration.

USAGE:
    bat [OPTIONS] [FILE]...
    bat <SUBCOMMAND>

OPTIONS:
    -A, --show-all                       Show non-printable characters (space, tab, newline, ..).
    -p, --plain                          Show plain style (alias for '--style=plain').
    -l, --language <language>            Set the language for syntax highlighting.
    -H, --highlight-line <N:M>...        Highlight lines N through M.
        --file-name <name>...            Specify the name to display for a file.
    -d, --diff                           Only show lines that have been added/removed/modified.
        --tabs <T>                       Set the tab width to T spaces.
        --wrap <mode>                    Specify the text-wrapping mode (*auto*, never, character).
    -n, --number                         Show line numbers (alias for '--style=numbers').
        --color <when>                   When to use colors (*auto*, never, always).
        --italic-text <when>             Use italics in output (always, *never*)
        --decorations <when>             When to show the decorations (*auto*, never, always).
        --paging <when>
            Specify when to use the pager, or use `-P` to disable (*auto*, never, always).

    -m, --map-syntax <glob:syntax>...
            Use the specified syntax for files matching the glob pattern ('*.cpp:C++').

        --theme <theme>                  Set the color theme for syntax highlighting.
        --list-themes                    Display all supported highlighting themes.
        --style <components>
            Comma-separated list of style elements to display (*auto*, full, plain, changes, header,
            grid, rule, numbers, snip).
    -r, --line-range <N:M>...            Only print the lines from N to M.
    -L, --list-languages                 Display all supported languages.
    -h, --help                           Print this help message.
    -V, --version                        Show version information.

ARGS:
    <FILE>...    File(s) to print / concatenate. Use '-' for standard input.

SUBCOMMANDS:
    cache    Modify the syntax-definition and theme cache

Note: `bat -h` prints a short and concise overview while `bat --help` gives all details.




% bat --help
bat 0.19.0 (c378c73)
A cat(1) clone with syntax highlighting and Git integration.

USAGE:
    bat [OPTIONS] [FILE]...
    bat <SUBCOMMAND>

OPTIONS:
    -A, --show-all
            Show non-printable characters like space, tab or newline. This option can also be used
            to print binary files. Use '--tabs' to control the width of the tab-placeholders.
    -p, --plain                                 
            Only show plain style, no decorations. This is an alias for '--style=plain'. When '-p'
            is used twice ('-pp'), it also disables automatic paging (alias for '--style=plain
            --pager=never').
    -l, --language <language>                   
            Explicitly set the language for syntax highlighting. The language can be specified as a
            name (like 'C++' or 'LaTeX') or possible file extension (like 'cpp', 'hpp' or 'md'). Use
            '--list-languages' to show all supported language names and file extensions.
    -H, --highlight-line <N:M>...               
            Highlight the specified line ranges with a different background color For example:
              '--highlight-line 40' highlights line 40
              '--highlight-line 30:40' highlights lines 30 to 40
              '--highlight-line :40' highlights lines 1 to 40
              '--highlight-line 40:' highlights lines 40 to the end of the file
              '--highlight-line 30:+10' highlights lines 30 to 40
        --file-name <name>...                   
            Specify the name to display for a file. Useful when piping data to bat from STDIN when
            bat does not otherwise know the filename. Note that the provided file name is also used
            for syntax detection.
    -d, --diff
            Only show lines that have been added/removed/modified with respect to the Git index. Use
            --diff-context=N to control how much context you want to see.
        --diff-context <N>                      
            Include N lines of context around added/removed/modified lines when using '--diff'.

        --tabs <T>                              
            Set the tab width to T spaces. Use a width of 0 to pass tabs through directly

        --wrap <mode>
            Specify the text-wrapping mode (*auto*, never, character). The '--terminal-width' option
            can be used in addition to control the output width.
        --terminal-width <width>
            Explicitly set the width of the terminal instead of determining it automatically. If
            prefixed with '+' or '-', the value will be treated as an offset to the actual terminal
            width. See also: '--wrap'.
    -n, --number                                
            Only show line numbers, no other decorations. This is an alias for '--style=numbers'

        --color <when>                          
            Specify when to use colored output. The automatic mode only enables colors if an
            interactive terminal is detected - colors are automatically disabled if the output goes
            to a pipe.
            Possible values: *auto*, never, always.
        --italic-text <when>                    
            Specify when to use ANSI sequences for italic text in the output. Possible values:
            always, *never*.
        --decorations <when>
            Specify when to use the decorations that have been specified via '--style'. The
            automatic mode only enables decorations if an interactive terminal is detected. Possible
            values: *auto*, never, always.
    -f, --force-colorization                    
            Alias for '--decorations=always --color=always'. This is useful if the output of bat is
            piped to another program, but you want to keep the colorization/decorations.
        --paging <when>
            Specify when to use the pager. To disable the pager, use --paging=never' or its
            alias,'-P'. To disable the pager permanently, set BAT_PAGER to an empty string. To
            control which pager is used, see the '--pager' option. Possible values: *auto*, never,
            always.
        --pager <command>                       
            Determine which pager is used. This option will override the PAGER and BAT_PAGER
            environment variables. The default pager is 'less'. To control when the pager is used,
            see the '--paging' option. Example: '--pager "less -RF"'.
    -m, --map-syntax <glob:syntax>...
            Map a glob pattern to an existing syntax name. The glob pattern is matched on the full
            path and the filename. For example, to highlight *.build files with the Python syntax,
            use -m '*.build:Python'. To highlight files named '.myignore' with the Git Ignore
            syntax, use -m '.myignore:Git Ignore'. Note that the right-hand side is the *name* of
            the syntax, not a file extension.
        --ignored-suffix <ignored-suffix>...
            Ignore extension. For example:
              'bat --ignored-suffix ".dev" my_file.json.dev' will use JSON syntax, and ignore '.dev'
        --theme <theme>                         
            Set the theme for syntax highlighting. Use '--list-themes' to see all available themes.
            To set a default theme, add the '--theme="..."' option to the configuration file or
            export the BAT_THEME environment variable (e.g.: export BAT_THEME="...").
        --list-themes                           
            Display a list of supported themes for syntax highlighting.

        --style <components>
            Configure which elements (line numbers, file headers, grid borders, Git modifications,
            ..) to display in addition to the file contents. The argument is a comma-separated list
            of components to display (e.g. 'numbers,changes,grid') or a pre-defined style ('full').
            To set a default style, add the '--style=".."' option to the configuration file or
            export the BAT_STYLE environment variable (e.g.: export BAT_STYLE="..").
            
            Possible values:
            
              * full: enables all available components (default).
              * auto: same as 'full', unless the output is piped.
              * plain: disables all available components.
              * changes: show Git modification markers.
              * header: show filenames before the content.
              * grid: vertical/horizontal lines to separate side bar
                      and the header from the content.
              * rule: horizontal lines to delimit files.
              * numbers: show line numbers in the side bar.
              * snip: draw separation lines between distinct line ranges.
    -r, --line-range <N:M>...                   
            Only print the specified range of lines for each file. For example:
              '--line-range 30:40' prints lines 30 to 40
              '--line-range :40' prints lines 1 to 40
              '--line-range 40:' prints lines 40 to the end of the file
              '--line-range 40' only prints line 40
              '--line-range 30:+10' prints lines 30 to 40
    -L, --list-languages                        
            Display a list of supported languages for syntax highlighting.

    -u, --unbuffered                            
            This option exists for POSIX-compliance reasons ('u' is for 'unbuffered'). The output is
            always unbuffered - this option is simply ignored.
        --diagnostic                            
            Show diagnostic information for bug reports.

        --acknowledgements                      
            Show acknowledgements.

    -h, --help                                  
            Print this help message.

    -V, --version                               
            Show version information.


ARGS:
    <FILE>...    
            File(s) to print / concatenate. Use a dash ('-') or no argument at all to read from
            standard input.

SUBCOMMANDS:
    cache    Modify the syntax-definition and theme cache

Note: `bat -h` prints a short and concise overview while `bat --help` gives all details.

• Review the man page

% fd -HIp release.*bat.1                                               
target/release/build/bat-76b65ecfe6dcc02b/out/assets/manual/bat.1
% man target/release/build/bat-76b65ecfe6dcc02b/out/assets/manual/bat.1 | tee
BAT(1)                                                                  BAT(1)



NAME
       bat - a cat(1) clone with syntax highlighting and Git integration.

USAGE
       bat [OPTIONS] [FILE]...

       bat cache [CACHE-OPTIONS] [--build|--clear]

DESCRIPTION
       bat  prints  the syntax-highlighted content of a collection of FILEs to
       the terminal. If no FILE is specified, or when FILE is  '-',  it  reads
       from standard input.

       bat  supports  a  large number of programming and markup languages.  It
       also communicates with git(1) to show modifications with respect to the
       git  index.   bat  automatically  pipes  its output through a pager (by
       default: less).

       Whenever the output of bat goes to  a  non-interactive  terminal,  i.e.
       when  the output is piped into another process or into a file, bat will
       act as a drop-in replacement for cat(1) and fall back to  printing  the
       plain file contents.


OPTIONS
       General  remarks: Command-line options like '-l'/'--language' that take
       values  can  be  specified  as  either  '--language   value',   '--lan-
       guage=value', '-l value' or '-lvalue'.

       -A, --show-all

              Show  non-printable  characters  like space, tab or newline. Use
              '--tabs' to control the width of the tab-placeholders.

       -p, --plain

              Only show plain style, no decorations.  This  is  an  alias  for
              '--style=plain'.  When  '-p' is used twice ('-pp'), it also dis-
              ables    automatic    paging    (alias    for     '--style=plain
              --pager=never').

       -l, --language <language>

              Explicitly  set  the  language for syntax highlighting. The lan-
              guage can be specified as a name (like 'C++' or 'LaTeX') or pos-
              sible   file   extension   (like  'cpp',  'hpp'  or  'md').  Use
              '--list-languages' to show all supported language names and file
              extensions.

       -H, --highlight-line <N:M>...

              Highlight  the specified line ranges with a different background
              color. For example:

              --highlight-line 40
                     highlights line 40

              --highlight-line 30:40
                     highlights lines 30 to 40

              --highlight-line :40
                     highlights lines 1 to 40

              --highlight-line 40:
                     highlights lines 40 to the end of the file

              --highlight-line 30:+10
                     highlights lines 30 to 40

       --file-name <name>...

              Specify the name to display for a file. Useful when piping  data
              to bat from STDIN when bat does not otherwise know the filename.
              Note that the provided file name is also used for syntax  detec-
              tion.

       -d, --diff

              Only  show  lines  that  have  been  added/removed/modified with
              respect to the Git index. Use '--diff-context=N' to control  how
              much context you want to see.

       --diff-context <N>...

              Include  N  lines of context around added/removed/modified lines
              when using '--diff'.

       --tabs <T>

              Set the tab width to T spaces. Use a width of  0  to  pass  tabs
              through directly

       --wrap <mode>

              Specify  the  text-wrapping mode (*auto*, never, character). The
              '--terminal-width' option can be used in addition to control the
              output width.

       --terminal-width <width>

              Explicitly  set the width of the terminal instead of determining
              it automatically. If prefixed with '+' or '-', the value will be
              treated  as  an  offset  to the actual terminal width. See also:
              '--wrap'.

       -n, --number

              Only show line numbers, no other decorations. This is  an  alias
              for '--style=numbers'

       --color <when>

              Specify  when  to  use  colored  output. The automatic mode only
              enables colors if an interactive terminal is detected.  Possible
              values: *auto*, never, always.

       --italic-text <when>

              Specify  when  to use ANSI sequences for italic text in the out-
              put. Possible values: always, *never*.

       --decorations <when>

              Specify when to use the decorations that have been specified via
              '--style'.  The  automatic  mode  only enables decorations if an
              interactive  terminal  is  detected.  Possible  values:  *auto*,
              never, always.

       -f, --force-colorization

              Alias  for '--decorations=always --color=always'. This is useful
              if the output of bat is piped to another program, but  you  want
              to keep the colorization/decorations.

       --paging <when>

              Specify when to use the pager. To disable the pager, use '--pag-
              ing=never' or its alias, -P. To disable the  pager  permanently,
              set  BAT_PAGER  to  an  empty  string. To control which pager is
              used, see the '--pager' option. Possible values: *auto*,  never,
              always.

       --pager <command>

              Determine  which  pager  is  used. This option will override the
              PAGER and BAT_PAGER environment variables. The default pager  is
              'less'.  To  control  when the pager is used, see the '--paging'
              option. Example: '--pager "less -RF"'.

              Note: By default, if the pager is set to 'less' (and no command-
              line  options are specified), 'bat' will pass the following com-
              mand line  options  to  the  pager:  '-R'/'--RAW-CONTROL-CHARS',
              '-F'/'--quit-if-one-screen'   and   '-X'/'--no-init'.  The  last
              option ('-X') is only used for 'less' versions older  than  530.
              The  '-R'  option  is needed to interpret ANSI colors correctly.
              The second option ('-F') instructs less to exit  immediately  if
              the  output size is smaller than the vertical size of the termi-
              nal. This is convenient for small files because you do not  have
              to  press  'q'  to  quit  the  pager. The third option ('-X') is
              needed to fix a bug with the '--quit-if-one-screen'  feature  in
              old  versions  of  'less'.  Unfortunately, it also breaks mouse-
              wheel support in 'less'.  If  you  want  to  enable  mouse-wheel
              scrolling  on  older  versions of 'less', you can pass just '-R'
              (as in the example above, this  will  disable  the  quit-if-one-
              screen  feature).  For  less 530 or newer, it should work out of
              the box.

       -m, --map-syntax <glob-pattern:syntax-name>...

              Map a glob pattern to an existing syntax name. The glob  pattern
              is  matched  on  the full path and the filename. For example, to
              highlight  *.build  files  with  the  Python  syntax,   use   -m
              '*.build:Python'.  To highlight files named '.myignore' with the
              Git Ignore syntax, use -m '.myignore:Git Ignore'.  Note that the
              right-hand  side  is the *name* of the syntax, not a file exten-
              sion.

       --theme <theme>

              Set the theme for syntax highlighting.  Use  '--list-themes'  to
              see  all  available  themes.   To  set  a default theme, add the
              '--theme="..."' option to the configuration file or  export  the
              BAT_THEME environment variable (e.g.: export BAT_THEME="...").

       --list-themes

              Display a list of supported themes for syntax highlighting.

       --style <style-components>

              Configure  which elements (line numbers, file headers, grid bor-
              ders, Git modifications, ..) to display in addition to the  file
              contents.  The  argument is a comma-separated list of components
              to display (e.g. 'numbers,changes,grid') or a pre-defined  style
              ('full').  To set a default style, add the '--style=".."' option
              to the configuration file or export  the  BAT_STYLE  environment
              variable (e.g.: export BAT_STYLE=".."). Possible values: *full*,
              auto, plain, changes, header, grid, rule, numbers, snip.

       -r, --line-range <N:M>...

              Only print the specified range of lines for each file. For exam-
              ple:

              --line-range 30:40
                     prints lines 30 to 40

              --line-range :40
                     prints lines 1 to 40

              --line-range 40:
                     prints lines 40 to the end of the file

              --line-range 30:+10
                     prints lines 30 to 40

       -L, --list-languages

              Display a list of supported languages for syntax highlighting.

       -u, --unbuffered

              This  option  exists  for  POSIX-compliance  reasons ('u' is for
              'unbuffered'). The output is always unbuffered - this option  is
              simply ignored.

       -h, --help

              Print this help message.

       -V, --version

              Show version information.

POSITIONAL ARGUMENTS
       <FILE>...

              Files  to print and concatenate. Use a dash ('-') or no argument
              at all to read from standard input.

SUBCOMMANDS
       cache - Modify the syntax-definition and theme cache.

FILES
       bat can also be customized with a configuration file. The  location  of
       the file is dependent on your operating system. To get the default path
       for your system, call:

       bat --config-file

       Alternatively, you can use the BAT_CONFIG_PATH environment variable  to
       point bat to a non-default location of the configuration file.

       To generate a default configuration file, call:

       bat --generate-config-file

ADDING CUSTOM LANGUAGES
       bat  supports  Sublime  Text .sublime-syntax language files, and can be
       customized to add additional languages to your local  installation.  To
       do  this,  add  the  .sublime-syntax language files to `$(bat --config-
       dir)/syntaxes` and run `bat cache --build`.

       Example:

            mkdir -p "$(bat --config-dir)/syntaxes"
            cd "$(bat --config-dir)/syntaxes"

            # Put new '.sublime-syntax' language definition files
            # in this folder (or its subdirectories), for example:
            git clone https://github.com/tellnobody1/sublime-purescript-syntax

            # And then build the cache.
            bat cache --build

       Once  the  cache  is  built,  the  new language will be visible in `bat
       --list-languages`.
       If you ever want to remove the custom  languages,  you  can  clear  the
       cache with `bat cache --clear`.


ADDING CUSTOM THEMES
       Similarly  to  custom  languages,  bat  supports  Sublime Text .tmTheme
       themes.  These can be installed to  `$(bat  --config-dir)/themes`,  and
       are added to the cache with `bat cache --build`.

MORE INFORMATION
       For more information and up-to-date documentation, visit the bat repo:
       https://github.com/sharkdp/bat



                                                                        BAT(1)

Pre-release checks

• Push all changes and wait for CI to succeed (before continuing with the
  next section).
• Optional: manually test the new features and command-line options. To do
  this, install the latest bat version again (to include the new syntaxes
  and themes).
• Run cargo publish --dry-run --allow-dirty to make sure that it will
  succeed later (after creating the GitHub release).

Release

• Create a tag and push it: git tag vX.Y.Z; git push origin tag vX.Y.Z.
  This will trigger the deployment via GitHub Actions.
• Go to https://github.com/sharkdp/bat/releases/new to create the new
  release. Select the new tag and also use it as the release title. For the
  release notes, copy the corresponding section from CHANGELOG.md and
  possibly add additional remarks for package maintainers.
  Publish the release.
• Check if the binary deployment works (archives and Debian packages should
  appear when the CI run for the Git tag has finished).
• Publish to crates.io by running cargo publish in a clean repository.
  The safest way to do this is to clone a fresh copy.

Post-release

• Prepare a new (empty) "unreleased" section at the top of CHANGELOG.md.

[Enselic]

Note that I introduced a new post-release section since I think we don't want to ship the unreleased section in production releases? Seems better to add that section right after the release has been made, I think?

[sharkdp]

Thank you very much. Looks great!

[Enselic]

Great! I'll go on and make the release then 👍

I have confirmed that bat v0.19.0 requires users of bat v0.18.3 to rebuild custom assets (which is needed due to lazy-loading of themes):

% bat tests/syntax-tests/source/BatTestCustomAssets/NoColorsUnlessCustomAssetsAreUsed.battestcustomassets 
[bat error]: The binary caches for the user-customized syntaxes and themes in '/Users/jobb/.cache/bat' are not compatible with this version of bat (0.19.0). To solve this, either rebuild the cache (bat cache --build) or remove the custom syntaxes/themes (bat cache --clear).
For more information, see:

  https://github.com/sharkdp/bat#adding-new-syntaxes--language-definitions