thoughtbot / thoughtbot/dotfiles
Add a CODING_STANDARDS.md for shell scripts
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
shorbash. Most ofbin/uses#!/bin/sh, butbin/replaceand
bin/bundler-searchuse&>, 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-portexits
0 when the port was already free, both before and after #789. Some scripts
inbin/useset -eand 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
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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