Document deprecation and breaking change strategy

[patrickarlt]

When we release 4.0 I think we should document how we make breaking changes to ArcGIS REST JS. We are generally pretty good about following SemVer and since we a comprehensive test suite it is easy to identify breaking changes. However I think we should give some care to how we INTENTIONALLY deprecate thinks and document and annouce these changes. In 4.0 for example:

• We have merged arcgis-rest-auth into arcgis-rest-request. This is a breaking change but we decided to still maintain arcgis-rest-auth for one major version to give people time to migrate.
• We have merged arcgis-rest-feature-layer and arcgis-rest-service-admin into arcgis-rest-feature-service but we are NOT maintaining the old packages to help users migrate.
• Major renames for ApiKey, UserSession and ApplicationCredentials also happened.

As a group I think we should decide if we want to hold users hands through changes like these. For example we ARE making a breaking change in the version number so do we think that is enough to clue users in to look at the changelog and update their apps or do we want to help them my marking these as deprecated in 4.0 and removing them at 5.0?

When we did v2 we just documented that changes and got on with it. https://esri.github.io/arcgis-rest-js/guides/whats-new-v2-0/ I'm wondering if we should do the same here.

[dbouwman]

I'm sure it's a lot of work, but Ember's strategy is nice from the consumer perspective. They implement all new features in the current major, at the same time adding messaging to all soon-to-be deprecated functions. The actual major release, is then just the dropping of all the deprecated functions.

If dev's keep up with the minor/patch releases through a major cycle, and they address all the warnings, then the major bump is a non-event, and results in a smaller bundle size b/c all the deprecated fns are now gone.

We can consider that as a strategy going from 4.x -> 5.x... but for the 4.x release itself, I think we should just move all the things, have a guide in the docs/changelog, and release it.

[noahmulfinger]

It seems like with the package name changes, it could be less clear for users since they can't just do an install @latest to update, so I lean towards having the old packages exist and just re-exporting the new package. Maybe there's a way to log out a deprecation warning whenever they import from the old package name?

I don't feel too strong about either direction, but I think the more important thing is it should be consistent across packages.

Kind of related to @dbouwman's comment, we could push the deprecation warnings to 3.x now so current installs will show the warning. But if 4.x is releasing pretty soon that won't reach many users.

[patrickarlt]

If dev's keep up with the minor/patch releases through a major cycle, and they address all the warnings, then the major bump is a non-event, and results in a smaller bundle size b/c all the deprecated fns are now gone.

As nice as this is I feel like work on REST JS tends to happen in sort bursts as we have time to work it rather then a really consistent cycle. Planning also happens in the same way. Maybe with automated releases this won't be too bad?

Maybe there's a way to log out a deprecation warning whenever they import from the old package name?

We would have to publish the old packages at 4.0 for compatibility and immediately npm deprecate them which logs on install. Logging on import would require some additional work.

---

Since I don't think 4.0 will be released for awhile given the release automation and doc issues I think we COULD restore the old packages and depreacte them as a warning. The real question remains should be and who should do the work.