Deprecation policy

[smilediver]

It would be nice if there was a more clear deprecation policy and more robust management. My proposed plan is:

1. Decide what the lifetime for deprecated features should be. Example: deprecated features are removed after they were deprecated for at least two minor releases: so if it was marked deprecated in 2.1, then it is removed in 2.3.
2. Document that in Readme/Wiki.
3. Mark everything already deprecated with AX_DEPRECATED(2.1). (Or maybe we should already remove old deprecated stuff right now?, cause some stuff is already deprecated since Cocos).
4. Add AX_DEPRECATED_NOTE(...) (name could be different) for marking things like macros, that can't have a deprecated attribute.
5. Remove AX_DEPRECATED_ATTRIBUTE.
6. Add AX_USE_DEPRECATED to turn on/off deprecated features. It can be optionally turned on by user, so they can choose to stay on the bleeding edge or use deprecated features. It would work like this:

    #if AX_USE_DEPRECATED
        AX_DEPRECATED(2.1) static Application* sharedApplication();
    #endif

Also, it would be nice if there was a more clear overall release schedule, like a new minor release every quarter, or something like that.

What do you think? If there's interest to that, I could take care of the code side of things.

[iAndyHD3]

Perhaps we should try to follow the semver specification/suggestions, it has pretty strong rules regarding deprecation and versioning

Before you completely remove the functionality in a new major release there should be at least one minor release that contains the deprecation so that users can smoothly transition to the new API.

Minor version Y (x.Y.z | x > 0) MUST be incremented if new, backward compatible functionality is introduced to the public API. It MUST be incremented if any public API functionality is marked as deprecated. It MAY be incremented if substantial new functionality or improvements are introduced within the private code. It MAY include patch level changes. Patch version MUST be reset to 0 when minor version is incremented.

[smilediver]

I'm not sure if full semver would work well in Axmol's case, since it does small breaking changes all the time, and it would end up with huge major versions really fast. To avoid that you'd need to maintain separate major and minor branches, and I don't think anyone wants to do that. But some concepts and ideas could be borrowed.

[solan-solan]

It would be good if deprecated api will be removed in the manner of one api - one commit to simplify existing code adaptation if it was not done before

[halx99]

#2136