Deprecate the pants() wrapper from around pants() targets. Update docs, and add a deprecation message
Review Request #903 - Created Aug. 15, 2014 and submitted
Deprecate the pants() wrapper from around pants() targets. Update docs, and add a deprecation message: *** pants() wrapper is obsolete and will be removed in a future release. See http://pantsbuild.github.io/build_files.html ***
Compile pants, saw new warning. Scanned the docs locally running build-support/bin/publish_docs.sh and made sure url in warning worked.
My first inclination was to just remove pants from goals/register.py and remove all pants() references from out BUILD files, but when I did, a very ugly message came out. Also, I realized that all of our documentation still referenced it, so anyone not tracking pants-devel. @Larry: When expunging pants() from documentation I hit something I'm unsure about as there seems to be a pants() reference in markdown for page() targets? Removing pants() references from BUILD files is mechanical (see shell cmd in updated docs) and will follow once I land the testprojects/ patch.
Things I unreservedly like: the deprecation; a fuller explanation in the docs, linked to from the error message. Things that make me hedge: intro docs that use strings w/out a "# Using old pants? Wrap this in pants(...)" Sad but true, Twitter has a big repo on old-Pants. For the sake of new Twitter-folk learning that old-Pants repo, I like pants() in the docs. I've been "resolving" this issue so far by procrastinating on updating the docs. OTOH, you're introducing a bunch of new folks to not-old Pants. And it'd be sad if they thought BUILD files need pants(). So... maybe compromise on a "# Using old pants? ..." comment? (Maybe one easily search-and-delete-able on that golden day when all Twitter's Pants are new?) (Or a better idea you're about to suggest?)
I've tried a few cases of asking old-pants to use strings. So far, all caught by TargetDefinitionException...of type <type 'str'>. I'll try some more, and report back if I get different messages. But so far, it seems we're YAY consistent: The following targets could not be loaded: src/java/com/twitter/foo/bar/baz => TargetDefinitionException: Error with src/java/com/twitter/foo/bar/baz/BUILD:baz: Expected elements of list to be (<class 'twitter.pants.targets.external_dependency.ExternalDependency'>, <class 'twitter.pants.targets.anonymous.AnonymousDeps'>, <class 'twitter.pants.base.target.Target'>), got value 3rdparty:guava of type <type 'str'>
Review request changed
Reverted changes to page.rst docs. Incorporated the errors you might get from older versions of Pants missing the pants() wrapper call.