Skip to content
This repository has been archived by the owner on Jul 4, 2023. It is now read-only.

Add description field to Formulae #39911

Closed
wants to merge 7 commits into from
Closed

Add description field to Formulae #39911

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
ef39f39
Add a desc field to Formula
adzenith May 19, 2015
e4499dd
ack: add description
adzenith May 20, 2015
11b089b
Info shows the desc if present
adzenith May 19, 2015
85da0a5
`brew search` can take a `--desc` argument to search descriptions
adzenith May 19, 2015
33f9222
audit looks for and validates 'desc'
adzenith May 19, 2015
bb6a599
`brew create` adds a `desc` field to the new formula
adzenith May 20, 2015
c71654f
example-formula.rb has a 'desc'
adzenith May 20, 2015
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
1 change: 1 addition & 0 deletions Library/Contributions/example-formula.rb
View file
Open in desktop
Expand Up @@ -9,6 +9,7 @@
# Homebrew does enforce that the name of the file and the class correspond.
# Check with `brew search` that the name is free.
class ExampleFormula < Formula
desc "An example formula" # shows up in `brew info`, and can be searched with `brew search --desc`.
homepage "https://www.example.com" # used by `brew home example-formula`.
revision 1 # This is used when there's no new version but it needs recompiling for another reason.
# 0 is default & unwritten.
Expand Down
1 change: 1 addition & 0 deletions Library/Formula/ack.rb
View file
Open in desktop
@@ -1,4 +1,5 @@
class Ack < Formula
desc "A search tool like grep, but optimized for programmers"
homepage "http://beyondgrep.com/"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A minor question here. Which style is better? Personally, I prefer homepage is at the top.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The homepage is more canonical, so to speak, but the desc is more relevant (to me as someone who doesn't know what the formula is). That's why I put the desc first. Obviously it's easy to move second if that's preferred. I put it first in brew create to match this, but can easily move it all below.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My own personal strong preference is that we put the desc as the last line of the initial block, i.e. under either the sha or revision. For some reason, having it as the top line is making me very uncomfortable, but I'm just weird.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would prefer to keep it above the sha and version, because the sha and version apply to a single version of the software, whereas the description deals with the software regardless of version (like the homepage). Is there a reason you'd want to have it down there?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For me at least, the initial formula block is in order of things I need to know most, that are most important to most people/formula authors.

I want to know where the formula is from first, I want to know where it's being download from next, and then I want to know what the checksum is for security. The formula description feels less important to me than any of those three things.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I first was in favor of “homepage then desc then the rest” but I read @adzenith’s comment and now agree with the “description first, then homepage, then the rest”. The desc is indeed the more relevant here, and the homepage’s URL doesn’t usually give you much information about the software (say the formula is “foobar”, the URL will likely be foobar.sourceforge.net or some-academic-website.edu/~doe/software/foobar) and you can open it quickly in your browser with brew home <formula>.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My two cents: Let's please not let this PR get bogged down with bike-shedding. As far as I know, brew does not enforce any rules about the order of items in the top of the class. So I can't see why we need to worry so very much about it. (My point being that once we start asking for opinions, everyone will have one, but really: is it that important?)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As far as I know, brew does not enforce any rules about the order of items in the top of the class.

This isn't quite true. It's not in the audit but the only things that move around in the initial block unless there's need for stable do is the version line, if there is one. That can go either below the URL or below the sha. But generally, although not audit-enforced, deviation from that tends to get asked to change. Whether that's just because formulae become a pain to update/compare/etc if all of them have different layouts or whether that's for another reason, I defer to the people who wrote the implementation.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This isn't quite true....

I didn't realize. Thanks for clarifying.

In that case, I suppose if we could get a quick ruling from the team, that would be great. I don't think it much matters where they pick, but I agree that having a convention is useful.

Again, my goal is to avoid protracted delay of the PR being merged because of bike-shedding.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, let's hold off the ordering discussion for now and just leave it as-is.

url "http://beyondgrep.com/ack-2.14-single-file"
sha256 "1d203cfbc52ce8f49e3992be1cd3e4d7d5dfb7daa3739e8628aa9858ccc5b9df"
Expand Down
27 changes: 27 additions & 0 deletions Library/Homebrew/cmd/audit.rb
View file
Open in desktop
Expand Up @@ -244,6 +244,32 @@ def audit_options
end
end

def audit_desc
# For now, only check the description when using `--strict`
return unless @strict

desc = formula.desc

unless desc and desc.length > 0
problem "Formula should have a desc (Description)."
return
end

# Make sure the formula name plus description is no longer than 80 characters
linelength = formula.name.length + ": ".length + desc.length
if linelength > 80
problem "Description is too long. \"name: desc\" should be less than 80 characters (currently #{linelength})."
end

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe also check whether desc is empty. As sometimes people forget to change the desc filed created by brew create.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good idea. Fixed!

if desc =~ %r[[Cc]ommandline]
problem "It should be \"command-line\", not \"commandline\"."
end

if desc =~ %r[[Cc]ommand line]
problem "It should be \"command-line\", not \"command line\"."
end
end

def audit_homepage
homepage = formula.homepage

Expand Down Expand Up @@ -706,6 +732,7 @@ def audit
audit_file
audit_class
audit_specs
audit_desc
audit_homepage
audit_deps
audit_conflicts
Expand Down
1 change: 1 addition & 0 deletions Library/Homebrew/cmd/create.rb
View file
Open in desktop
Expand Up @@ -124,6 +124,7 @@ def template; <<-EOS.undent
# PLEASE REMOVE ALL GENERATED COMMENTS BEFORE SUBMITTING YOUR PULL REQUEST!

class #{Formulary.class_s(name)} < Formula
desc ""
homepage ""
url "#{url}"
<% unless version.nil? or version.detected_from_url? %>
Expand Down
2 changes: 2 additions & 0 deletions Library/Homebrew/cmd/info.rb
View file
Open in desktop
Expand Up @@ -94,6 +94,8 @@ def info_formula f

puts "#{f.name}: #{specs*', '}#{' (pinned)' if f.pinned?}"

puts f.desc if f.desc

puts f.homepage

if f.keg_only?
Expand Down
7 changes: 7 additions & 0 deletions Library/Homebrew/cmd/search.rb
View file
Open in desktop
Expand Up @@ -20,6 +20,13 @@ def search
exec_browser "https://admin.fedoraproject.org/pkgdb/packages/%2A#{ARGV.next}%2A/"
elsif ARGV.include? '--ubuntu'
exec_browser "http://packages.ubuntu.com/search?keywords=#{ARGV.next}&searchon=names&suite=all&section=all"
elsif ARGV.include? '--desc'
query = ARGV.next
Formula.each do |formula|
if formula.desc =~ query_regexp(query)
puts "#{formula.name}: #{formula.desc}"
end
end
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't use Formula.names. Instead please use Formula.each/map/select.

elsif ARGV.empty?
puts_columns Formula.names
elsif ARGV.first =~ HOMEBREW_TAP_FORMULA_REGEX
Expand Down
13 changes: 13 additions & 0 deletions Library/Homebrew/formula.rb
View file
Open in desktop
Expand Up @@ -163,6 +163,12 @@ def bottle
Bottle.new(self, bottle_specification) if bottled?
end

# The description of the software.
# @see .desc
def desc
self.class.desc
end

# The homepage for the software.
# @see .homepage
def homepage
Expand Down Expand Up @@ -685,6 +691,7 @@ def recursive_requirements(&block)
def to_hash
hsh = {
"name" => name,
"desc" => desc,
"homepage" => homepage,
"versions" => {
"stable" => (stable.version.to_s if stable),
Expand Down Expand Up @@ -921,6 +928,12 @@ class << self
# @private
attr_reader :keg_only_reason

# @!attribute [w]
# A one-line description of the software. Used by users to get an overview
# of the software and Homebrew maintainers.
# Shows when running `brew info`.
attr_rw :desc

# @!attribute [w]
# The homepage for the software. Used by users to get more information
# about the software and Homebrew maintainers as a point of contact for
Expand Down