Development Policies

Geoffrey McGill edited this page Jan 24, 2017 · 2 revisions

Index

  1. Obsolete And Breaking Changes

Obsolete Attribute And Breaking Changes

The goal is to never have to use the ObsoleteAttribute, but sometimes it's required.

Any use of [Obsolete] attribute must include a message with instructions on how to modify existing code to now comply with new api.

If the [Obsolete] attribute is applied, as Bridge proceeds through subsequent minor and major releases, the state of [Obsolete] will track the escalation steps outlined in the following table:

NOTE: When the [Obsolete] attribute is first applied, a new Issue is to be pre-created documenting each step of this process. The future milestone of each Issue is to be set at that time.

Phase Release Description Compiler Message
😞 Current [Obsolete("descriptive message on how to work-around change. See Issue #1234 for more information.")] Warning – compilation will continue
😠 Next Major [Obsolete("descriptive message on how to work-around change. See Issue #1234 for more information.", true)] Error – compilation will fail
😡 Next Next Major The obsolete Class or Member is removed from source Breaking Change – compilation will fail

As an example, if the [Obsolete] attribute is applied to a Method in Bridge 15.8, the compiler will throw a Warning message, but compilation will continue:

[Obsolete("Please use DoSomethingElse(). See Issue #1234 for more information.")]
public void DoSomething() { }

Then in Bridge 16.0 (Next Major release), the error flag will be set. The compiler will throw an Error message, and compilation will fail:

[Obsolete("Please use DoSomethingElse(). See Issue #1234 for more information.", true)]
public void DoSomething() { }

Then in Bridge 17.0 (Next Next Major release), the DoSomething Method would be completely removed from the project.

// Nothing to see here