Skip to content

Conversation

@jonpryor
Copy link
Contributor

Context: dotnet/android#1078

xamarin-android uses mono-api-html and mono-api-info in order to
perform API comparisons; see e.g. 4e45904.

A recent problem has arisen regarding "inter-API-level diffs": there
are many API changes which we consider to be acceptable, and thus
would like to ignore. Unfortunately, mono-api-html doesn't support
ignoring many of these constructs, e.g. base class changes:

<h3>Type Changed: Android.Preferences.CheckBoxPreference</h3>
Modified base type: <span class='removed removed-inline removed-breaking-inline'>Android.Preferences.Preference</span> <span class='added '>Android.Preferences.TwoStatePreference</span>

and property type changes:

<h3>Type Changed: Android.Views.InputEvent</h3>
<p>Modified properties:</p>
<pre>
<div data-is-breaking>	public <span class='added added-breaking-inline'>abstract</span> int DeviceId { get; }
</div><div data-is-breaking>	public <span class='added added-breaking-inline'>abstract</span> InputSourceType Source { get; }

Overhaul the mono-api-html "ignore" infrastructure:

  • Introduce ignore "scoping". Previously, the ignore options would
    only match the member text against any provided regular
    expression. Thus, mono-api-html -r ToString would ignore all
    members containing ToString. Furthermore, there was no way to
    restrict the ignore to a particular type. Expand the regex
    semantics so that the declaring type is used as a "prefix" for the
    to-be-matched text. For example, if a class Example is removed,
    mono-api-html will now match the following value against any
    -r regular expressions:

    Example: Removed type
    
  • Add a mono-api-html -v option, to control output verbosity.
    When specified, mono-api-html will print out available -r/etc.
    option values:

    $ mono-api-html expected.xml new.xml -v
    Possible -a value: Android.Resource: Added fields: public static const int AccessibilityEventTypes;
    Possible -r value: Android.Preferences.CheckBoxPreference: Modified base type: 'Android.Preferences.Preference' to 'Android.Preferences.TwoStatePreference'
    Possible -r value: Android.Views.InputEvent: Modified properties: public int DeviceId { get; }
    Possible -n value: Android.Views.UnavailableException: Added type
    ...
    

Additionally, allow mono-api-html to take a
Mono.Options.ResponseFileSource, which allows @response-files to
be used as command-line options.

Context: dotnet/android#1078

xamarin-android uses `mono-api-html` and `mono-api-info` in order to
perform API comparisons; see e.g. 4e45904.

A recent problem has arisen regarding "inter-API-level diffs": there
are many API changes which we consider to be acceptable, and thus
would like to ignore. Unfortunately, `mono-api-html` doesn't support
ignoring many of these constructs, e.g. base class changes:

	<h3>Type Changed: Android.Preferences.CheckBoxPreference</h3>
	Modified base type: <span class='removed removed-inline removed-breaking-inline'>Android.Preferences.Preference</span> <span class='added '>Android.Preferences.TwoStatePreference</span>

and property type changes:

	<h3>Type Changed: Android.Views.InputEvent</h3>
	<p>Modified properties:</p>
	<pre>
	<div data-is-breaking>	public <span class='added added-breaking-inline'>abstract</span> int DeviceId { get; }
	</div><div data-is-breaking>	public <span class='added added-breaking-inline'>abstract</span> InputSourceType Source { get; }

Overhaul the `mono-api-html` "ignore" infrastructure:

  * Introduce ignore "scoping". Previously, the ignore options would
    only match the *member* text against any provided regular
    expression. Thus, `mono-api-html -r ToString` would ignore *all*
    members containing `ToString`. Furthermore, there was no way to
    restrict the ignore to a particular type. Expand the regex
    semantics so that the declaring type is used as a "prefix" for the
    to-be-matched text. For example, if a class `Example` is removed,
    `mono-api-html` will now match the following value against any
    `-r` regular expressions:

        Example: Removed type

  * Add a `mono-api-html -v` option, to control output verbosity.
    When specified, `mono-api-html` will print out available `-r`/etc.
    option values:

        $ mono-api-html expected.xml new.xml -v
        Possible -a value: Android.Resource: Added fields: public static const int AccessibilityEventTypes;
        Possible -r value: Android.Preferences.CheckBoxPreference: Modified base type: 'Android.Preferences.Preference' to 'Android.Preferences.TwoStatePreference'
        Possible -r value: Android.Views.InputEvent: Modified properties: public int DeviceId { get; }
        Possible -n value: Android.Views.UnavailableException: Added type
        ...

Additionally, allow `mono-api-html` to take a
`Mono.Options.ResponseFileSource`, which allows `@response-files` to
be used as command-line options.
@akoeplinger
Copy link
Member

@monojenkins backport 2018-02

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants