Improve deprecated option handling to allow options hinting beyond deprecation version.

Review Request #3369 - Created Jan. 23, 2016 and submitted

Information
Kris Wilson
pants
kwlzn/options_lifecycle
2832
Reviewers
pants-reviews
benjyw, jsirois, molsen, nhoward_tw, stuhood, zundel

Currently the deprecated_version of deprecated options are sanity checked against the current pants version. This check disallows deprecated options from existing beyond their expiration release, which limits the ability of pants to provide useful options alternative hinting outside of non-fatal warnings. Our experience at Twitter has been that users readily ignore these warnings and furthermore they are easily lost in a barrage of other output and hidden away in CI logs, etc. Users are later surprised when these deprecated options are excised and thus actually begin failing with no hinting.

This RB paves the way for new handling of deprecated options that facilitates display of hint information at the time of execution failure.

The proposed options deprecation lifecycle is thus:

1) Options are marked deprecated at release X. From here on, pants throws deprecation warnings to users until release X ships.
2) Once pants hits release X, the deprecated options begin breaking by throwing exceptions that include deprecation hints. Code that depends on these options can then go away.
3) At some point well into the future (ideally spanning multiple OSS releases to allow for disparate release cycles from OSS vs private), the deprecated options and hints themselves can then be removed.

This RB also temporarily restores the deprecated --test-junit-suppress-output option with the new behavior as a first stake towards improved options deprecation handling (and to avoid UX issues in our current internal release).


  • Relax check for expired versions in deprecated options.
  • Implement version checking for deprecated options at usage time with a conditional error or warning.
  • Relax wording ("will be removed" et al) to generalize deprecation notice tense in help and warnings.
  • Restore --test-junit-suppress-output with a deprecation_version of 0.0.64.
  • Test coverage.

CI is green @ https://travis-ci.org/pantsbuild/pants/builds/104225026


[illuminati pants (kwlzn/options_lifecycle)]$ ./pants test.junit --suppress-output
INFO] Detected git repository at /Users/kwilson/dev/pants on branch kwlzn/options_lifecycle

18:17:38 00:00 [main]
               (To run a reporting server: ./pants server)
18:17:38 00:00   [setup]
18:17:38 00:00     [parse]
18:17:39 00:01   [complete]
               FAILURE
Exception caught: (<class 'pants.option.errors.DeprecatedOptionError'>)

Exception message: Option 'suppress_output' in scope 'test.junit' is deprecated and removed in version 0.0.64. Use --output-mode instead.


[illuminati pants (kwlzn/options_lifecycle)]$ ptcm
INFO] Detected git repository at /Users/kwilson/dev/pants on branch kwlzn/options_lifecycle

18:14:42 00:00 [main]
               (To run a reporting server: ./pants server)
18:14:42 00:00   [setup]
18:14:42 00:00     [parse]INFO] Operating on changed 6 target(s): 
        * src/python/pants/backend/jvm/tasks:junit_run
        * src/python/pants/base:deprecated
        * src/python/pants/help
        * src/python/pants/option
        * tests/python/pants_test/base:deprecated
        * tests/python/pants_test/option:testing

               Executing tasks in goals: bootstrap -> imports -> unpack-jars -> deferred-sources -> gen -> jvm-platform-validate -> resolve -> resources -> compile -> test -> test-changed
...
18:14:43 00:01     [pytest]
18:14:43 00:01       [run]
                     ============== test session starts ===============
                     platform darwin -- Python 2.7.10 -- py-1.4.30 -- pytest-2.6.4
                     plugins: timeout
                     collected 83 items 

                     tests/python/pants_test/option/test_arg_splitter.py .........
                     tests/python/pants_test/option/test_options.py ....................................
                     tests/python/pants_test/option/test_option_value_container.py .......
                     tests/python/pants_test/option/test_options_bootstrapper.py .......
                     tests/python/pants_test/option/test_custom_types.py ..
                     tests/python/pants_test/option/test_config.py ...
                     tests/python/pants_test/option/test_options_fingerprinter.py .....
                     tests/python/pants_test/option/test_optionable.py .
                     tests/python/pants_test/base/test_deprecated.py .............

                     =========== 83 passed in 3.10 seconds ============
                     Name                                         Stmts   Miss Branch BrMiss  Cover
                     ------------------------------------------------------------------------------
                     No data to report.

18:14:48 00:06     [junit]
18:14:48 00:06     [go]
18:14:48 00:06     [node]
18:14:48 00:06   [test-changed]
18:14:48 00:06     [test-changed]
18:14:48 00:06   [complete]
               SUCCESS
Kris Wilson
Benjy Weinberger
Eric Ayers
Benjy Weinberger
Nick Howard (Twitter)
Kris Wilson
Eric Ayers
Kris Wilson
Review request changed

Status: Closed (submitted)

Change Summary:

thanks Benjy, Eric & Nick! submitted @ 055a36d3de496e8367956ac573041f90a063d44f

Loading...