bump-formula-version errors and usage documentation is unclear

[geuis]

brew config && brew doctor:

HOMEBREW_VERSION: 1.5.1-9-gea0af7d
ORIGIN: https://github.com/Homebrew/brew
HEAD: ea0af7d1af3a6b44338656739a76cf5b86f2e00f
Last commit: 5 hours ago
Core tap ORIGIN: https://github.com/Homebrew/homebrew-core
Core tap HEAD: 40207f8da316843b68bf07d9e05b261a6285628e
Core tap last commit: 3 hours ago
HOMEBREW_PREFIX: /usr/local
HOMEBREW_DEV_CMD_RUN: 1
HOMEBREW_NO_ANALYTICS_THIS_RUN: 1
CPU: octa-core 64-bit haswell
Homebrew Ruby: 2.3.3 => /usr/local/Homebrew/Library/Homebrew/vendor/portable-ruby/2.3.3/bin/ruby
Clang: 8.1 build 802
Git: 2.13.1 => /usr/local/bin/git
Curl: 7.54.0 => /usr/bin/curl
Perl: /usr/bin/perl
Python: /usr/local/bin/python => /usr/local/Cellar/python/2.7.13/Frameworks/Python.framework/Versions/2.7/bin/python2.7
Ruby: /usr/local/bin/ruby => /usr/local/Cellar/ruby/2.4.2_1/bin/ruby
Java: 1.8.0_131
macOS: 10.12.6-x86_64
Xcode: 8.3.3
CLT: 9.2.0.0.1.1510905681
X11: 2.7.11 => /opt/X11
Please note that these warnings are just used to help the Homebrew maintainers
with debugging if you file an issue. If everything you use Homebrew for is
working fine: please don't worry or file an issue; just ignore this. Thanks!

Warning: "config" scripts exist outside your system or Homebrew directories.
`./configure` scripts often look for *-config scripts to determine if
software packages are installed, and what additional flags to use when
compiling and linking.

Having additional scripts in your path can confuse software installed via
Homebrew if the config script overrides a system or Homebrew provided
script of the same name. We found the following "config" scripts:
  /opt/salt/bin/python-config
  /opt/salt/bin/python2-config
  /opt/salt/bin/python2.7-config
  /opt/salt/bin/x86_64-apple-darwin15.6.0-pkg-config

Warning: You have unlinked kegs in your Cellar
Leaving kegs unlinked can lead to build-trouble and cause brews that depend on
those kegs to fail to run properly once built. Run `brew link` on these:
  docker

Warning: Your Xcode (8.3.3) is outdated.
Please update to Xcode 9.2 (or delete it).
Xcode can be updated from the App Store.

Please always follow these steps:

• Confirmed this is a problem with running a brew command and not brew installing or the post-install behavior of one or more formulae? If it's a formulae-specific problem please file this issue at the relevant tap e.g. for Homebrew/homebrew-core https://github.com/Homebrew/homebrew-core/issues/new
• Ran brew update and retried your prior step?
• Ran brew doctor, fixed all issues and retried your prior step?
• Ran brew config and brew doctor and included their output with your issue?

To help us debug your issue please explain:

• What you were trying to do (and why)
  Updating the ffmpeg formula to allow the --with-librsvg option to be available.

• What happened (include command output)
  The instructions on updating a formula are vague, so I did the following:

1. brew edit ffmpeg and made the changes.
2. Then built ffmpeg from source with --build-from-source and verified my changes worked.
3. Then /usr/local/Homebrew/$ brew bump-formula-pr ffmpeg but got the error Error: ffmpeg: no --url= argument specified!.

• What you expected to happen
  Unclear. No written guidance is given on how to use this feature. The instructions at https://docs.brew.sh/How-To-Open-a-Homebrew-Pull-Request.html say:

Use brew bump-formula-pr to do everything (i.e. forking, committing, pushing) with a single command. Run brew bump-formula-pr --help to learn more.

The --help text is also unclear as to how to exactly use the bump-forumla-pr command.

brew bump-formula-pr [--devel] [--dry-run [--write]] [--audit|--strict] [--mirror=URL] [--version=version] [--message=message] (--url=URL --sha256=sha-256|--tag=tag --revision=revision) formula:
    Creates a pull request to update the formula with a new URL or a new tag.

    If a URL is specified, the sha-256 checksum of the new download must
    also be specified. A best effort to determine the sha-256 and formula
    name will be made if either or both values are not supplied by the user.

    If a tag is specified, the git commit revision corresponding to that
    tag must also be specified.

    If --devel is passed, bump the development rather than stable version.
    The development spec must already exist.

    If --dry-run is passed, print what would be done rather than doing it.

    If --write is passed along with --dry-run, perform a not-so-dry run
    making the expected file modifications but not taking any git actions.

    If --audit is passed, run brew audit before opening the PR.

    If --strict is passed, run brew audit --strict before opening the PR.

    If --mirror=URL is passed, use the value as a mirror URL.

    If --version=version is passed, use the value to override the value
    parsed from the URL or tag. Note that --version=0 can be used to delete
    an existing version override from a formula if it has become redundant.

    If --message=message is passed, append message to the default PR
    message.

    If --no-browse is passed, don't pass the --browse argument to hub
    which opens the pull request URL in a browser. Instead, output it to the
    command line.

    Note that this command cannot be used to transition a formula from a
    URL-and-sha256 style specification into a tag-and-revision style
    specification, nor vice versa. It must use whichever style specification
    the preexisting formula already uses.

I tried using the ffmpeg formula url with brew bump-formula-pr --url=https://github.com/Homebrew/homebrew-core/blob/master/Formula/ffmpeg.rb --version=3.4.1 --dry-run ffmpeg but got the following error message:

==> Downloading https://github.com/Homebrew/homebrew-core/blob/master/Formula/ffmpeg.rb
Already downloaded: /Users/charles/Library/Caches/Homebrew/ffmpeg-3.4.1.rb
==> brew update
==> replace nil with nil
Error: no implicit conversion of nil into String
Please report this bug:
  https://docs.brew.sh/Troubleshooting.html
/usr/local/Homebrew/Library/Homebrew/extend/string.rb:39:in `gsub!'
/usr/local/Homebrew/Library/Homebrew/extend/string.rb:39:in `gsub!'
/usr/local/Homebrew/Library/Homebrew/dev-cmd/bump-formula-pr.rb:54:in `block in inreplace_pairs'
/usr/local/Homebrew/Library/Homebrew/dev-cmd/bump-formula-pr.rb:50:in `each'
/usr/local/Homebrew/Library/Homebrew/dev-cmd/bump-formula-pr.rb:50:in `inreplace_pairs'
/usr/local/Homebrew/Library/Homebrew/dev-cmd/bump-formula-pr.rb:263:in `bump_formula_pr'
/usr/local/Homebrew/Library/Homebrew/brew.rb:100:in `<main>'

• Step-by-step reproduction instructions (by running brew commands)
  Included above.

Clearly I'm not doing something correctly. Willing to write better documentation if some can explain what to do.

[alyssais]

--url is supposed to be the URL of the release archive, not the URL of the formula. We'd definitely like PRs to improve documentation/error messaging around this.

It might also be worth not making --url mandatory in cases like this. @ilovezfs what do you think?

[alyssais]

(This isn't covered by #3729, is it?)

[ilovezfs]

I think the current behavior is correct and don't favor changing it. If you have further questions about usage, feel free to ask @geuis