We keep confusing people by using the magical word revision to mean different things.

We have:

• Bottle revisions:

bottle do
  revision 1
  sha256 "41af286dc0b172ed2f1ca934fd2278de4a1192302ffa07087cea2682e7d372e3" => :blah
end

• Git revisions:

url "https://github.com/magic/unicorns.git",
    :tag => "unicorn-1",
    :revision => "eefc6ed865ca20447afc293c986676933dbfb137"

• Formulae revisions:

url "https://example.org/example.tar.gz"
sha256 "13550350a8681c84c861aac2e5b440161c2b33a3e4f302ac680ca5b686de48de"
revision 1

Particularly confusing to new contributors is that we have an audit mechanism that nudges people to remove an unnecessary revision, and we see repeated examples of people removing the git commit revision rather than the revision 1.

We need to move away, long-term, from using the same keyword to represent different things, particularly where those things are used in close proximity on a regular basis. It'd probably be easier to change formulae/bottle meaning of revision, IMO, but discuss at will.