Skip to content

Add a CODING_STANDARDS.md for shell scripts #794

Description

@purinkle

We review shell scripts against standards that live in people's heads. Writing
them down would make review fair and would let us automate the parts a machine
can check.

#789 is the example. The review produced three findings against rules that
appear nowhere in this repo. All three came from one maintainer's private
config. The contributor had followed every rule we actually publish.

Worth deciding and recording:

  • POSIX sh or bash. Most of bin/ uses #!/bin/sh, but bin/replace and
    bin/bundler-search use &>, which is a bashism. Pick one and fix the
    outliers.
  • Which ShellCheck rules we enforce. See Run ShellCheck over bin/ in CI #792.
  • Whether a script should report failure to its caller. bin/clear-port exits
    0 when the port was already free, both before and after Clear a port held by more than one process #789. Some scripts
    in bin/ use set -e and some do not.
  • Comment and usage message style.
  • Whether commit titles follow a keyword list, and if so, which one.

The last point matters most for review. A rule we can point at is a standard.
A rule we cannot is a preference, and holding a contributor to it is unfair.

Related: #793 covers CONTRIBUTING.md, and should link here rather than
repeat any of it.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions