Screwdriver: Command usage limited to 1024 bytes

[jeffreytolar]

What happened:

I maintain a shared command; I recently added to the documentation (usage) to provide more detail, and discovered that the usage field is limited to only 1024 characters:

15:49:15.198 $ sd-cmd validate -f "$SD_COMMAND_PATH"
15:49:15.473 ERROR: Command is not valid for the following reasons:
15:49:15.473 "usage" length must be less than or equal to 1024 characters long

What you expected to happen:

Commands should be allowed to have as much documentation as needed. 1KB isn't very much text, and for commands having many options, is limiting the effectiveness of the the docs.

There likely should be some limit to how big the usage can grow, but hopefully larger than 1kb. Perhaps 4kb or 8kb?

For comparison, some lengths of various man pages on rhel6:

man page | length
--- | ---
cat(1) | ~2.5k
scp(1) | ~6.5k
ls(1) | ~10k
git(1) | ~27k

How to reproduce it:

Example sd-command.yaml:

---
namespace: test
name: usage-too-long
version: '0.1'
description: Example validation failure
usage: |
  sd-cmd exec test/usage-too-long@<VERSION> [OPTIONS]

  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse condimentum pretium lorem et tempor. Aenean et mauris porta, tempor ipsum at, hendrerit orci. Quisque euismod magna enim, eget ornare purus bibendum quis. Donec ex nisl, tincidunt faucibus velit ut, faucibus posuere dolor. Aliquam hendrerit sapien ex, et suscipit ante tincidunt cursus. Nunc hendrerit porttitor nulla, sit amet interdum massa faucibus ut. Mauris vel eros tortor. Nulla ac augue sed leo sagittis hendrerit. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Donec erat erat, pharetra vel odio ac, auctor faucibus leo. Duis euismod convallis dolor, vitae tincidunt sapien accumsan condimentum. Proin dapibus, urna id dapibus cursus, erat lectus volutpat lacus, ac dictum purus nibh quis massa. Nam lacus lorem, congue nec congue eget, venenatis egestas enim.

  In ultrices molestie eleifend. Vestibulum tincidunt convallis eros ut maximus. Quisque eget enim sed libero pretium sagittis. Ut eu massa dolor posuere.

maintainer: [email protected]
format: binary
binary:
    file: /usr/bin/wc

[tkyi]

This value is set here and is easily configurable (https://github.com/screwdriver-cd/data-schema/blob/master/config/command.js#L50). Open to changing it to whatever size sounds reasonable.
cc: @jithin1987

[jithine]

I am good with bumping to 4kb

[tkyi]

This issue should be resolved with screwdrivercd/screwdriver:v0.5.654