thoughtbot / thoughtbot/dotfiles

Add a CODING_STANDARDS.md for shell scripts

Open
#794 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Shell
Stars
8.2k
Forks
1.8k
Avg merge
10d 14h
Merged PRs (30d)
1

Description

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 #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 #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.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading #789 and #792, then inspect the shell entry points in bin/, especially bin/replace, bin/bundler-search, and bin/clear-port. Done means the agreed shell, ShellCheck, failure-reporting, comment, usage, and commit-title rules are recorded in CODING_STANDARDS.md, required outliers are fixed, and CONTRIBUTING.md links to it.

Written by the indexing model from the issue text.

Assessment

Tech stack
bash, shell
Domain
documentation, tooling
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.