Deprecation policy and procedure

[SimiHunjan]

This discussion is to formalize a process for deprecating features in the SDKs. This should include all the tasks that required when something has been identified to be deprecated.

[rwalworth]

An initial plan I came up with to get the conversation started:

1. Pre-Deprecation Planning

We need to ensure there's a solid reason and viable alternatives before any deprecation action is taken. We should evaluate the need for the deprecation (e.g., security risk, maintenance cost, better alternatives, tech debt) and get a good understanding of its impact. This should involve discussion with community members and apps/wallets and we should reach out to those teams to make sure they participate and provide feedback. All of the information regarding the deprecation should be put into a document that should live in this repo. We should come up with a template deprecation document that we can follow to make sure the deprecation contains all the information we want it to hold.

As part of the deprecation information, a deprecation timeline should be discussed and documented. This includes:

• Deprecation Notice Date: when are we going to formally notify the community that a feature is going to be deprecated? And how are we going to notify? Discord/X? I might like the idea of an sdk-deprecations channel in Discord so all deprecation information is consolidated in one place, and we can provide links to the deprecation docs so anyone can see all of the information about the deprecation and the decided timeline.
• Feature Deprecation Date: when is the feature going to be formally deprecated? And in what SDK release will the feature be deprecated? I propose a timeline of at least one month (I could be convinced to do more) between the Deprecation Notice Date and the actual deprecation. It should be noted that the actual deprecations of each SDK may not match exactly with the date specified in this document, but it should be at least within a couple days. The deprecation status of each SDK should be tracked in this document.
• Feature Removal Date: what is the date the deprecated feature will be removed? It might be easier to just remove all deprecated features every major release, but we could also choose to remove a deprecated feature after, say, 6 months? Or another specified amount of time. This could also mean, instead of removal, when support for a deprecated feature will cease. This should be clearly communicated. If a date is selected, it should be tracked in the deprecation doc. I vote for just the removal of them every major release, but am open to discussion on this.

Once these dates are discussed with sufficient feedback from community members and stakeholders, the deprecation is finalized. Upon reaching the Deprecation Notice Date, an announcement should be made of the deprecation.

Step Actions

1. Deprecation document put up for PR in this repo by those proposing a deprecation. This document should follow a specified template that will contain items such as explanation and reasonings for deprecation, findings for alternative solutions, description of impact, Deprecation Notice Date, Feature Deprecation Date, Feature Removal Date, and other items we may deem necessary (which we can/will put in the template).
2. Invitations to review and provide feedback are sent out to community members and main stakeholders (i.e. apps, wallets, etc.).
3. Discuss and update deprecation document if necessary with new findings, feedback, etc.
4. Merge PR into repo when document is finalized.
5. Announcement made of the deprecated feature upon reaching the Deprecation Notice Date.

2. Implementation of Deprecation

The deprecations specified in the deprecation doc should be worked and any decided alternatives implemented when close to the Feature Deprecation Date. It would be up to the maintainers/contributors of each SDK to determine how much time they need to be able to get the deprecation and any associated work merged. The deprecation work should include, but is not limited to:

• In-code changes: this could include log warnings, deprecation tags, etc., whatever is needed to notify a user when building, running, etc that they are using a deprecated feature.
• Update documentation: this includes in-code documentation, as well as generated or any extra provided documentation. The deprecated method should be removed and replaced with alternatives, if applicable.
• Update examples: any provided code examples or snippets should no longer use the deprecation, and the "proper way" to utilize a feature should be shown.

Upon reaching the Feature Deprecation Date, the deprecation should be included in a formal SDK release, and the deprecation doc updated to include the date of the release for each SDK that contains the deprecation. Sufficient documentation should be provided in the SDK releases on GitHub, as well as a migration guide section in the deprecation doc (or the deprecation doc can just contain links to the SDK release notes for each SDK so this information can be accessed that way as well). There should be a clear Deprecated header and a Migration header, to show what is deprecated, and how a user should migrate to use the non-deprecated feature, as well as code examples. A great example of what this could look like can be found in this (I also think release notes should be templated and the template stored in this repo as well so all SDK release notes look similar).

Step Actions

1. SDK maintainers and contributors work to deprecate the feature and implement alternative solution, if applicable.
2. The deprecation is merged as a part of a release of that SDK.
3. The SDK containing the deprecation is released, as well as documentation and sufficient release notes describing the deprecation.
4. The deprecation document is updated with the date (which should be on or close to the Feature Deprecation Date) and release version of the SDK release, as well as any other needed information.

3. Communication

The community should be notified of the deprecation in the release the same way we notified about the deprecation as we planned in step 1. Again, I propose an sdk-deprecations channel in Discord to consolidate these notices. After the release and announcement, support should be provided to users that need assistance with migrating. This involves maintainers and contributors being active on Discord to answer questions and make it an easy migration process for users. The community should also be monitored so feedback can be collected and properly addressed.

Step Actions

1. Announce the now-deprecated status of the deprecated feature (we could template-ize these announcements as well!)
2. SDK maintainers and contributors provide assistance to those attempting to migrate on Discord.

4. Deprecation Removal

While the formal removal of the deprecation will happen at a specified date, the notifications and announcements of its removal should start months ahead. I propose four different announcements of the removal of deprecated features (again, using the means we establish in step 1). I propose an announcement three months prior, one month prior, two weeks prior, and one day prior. This should provide users with plenty of notice and time to do their migrations and prepare for the removal.

The deprecations should be removed when close to the Feature Removal Date. Again, it would be up to the maintainers/contributors of each SDK to determine how much time they need to be able to get the deprecation removed. Upon reaching the Feature Removal Date (whether that's an actually decided-upon date, or a major version upgrade), the SDKs should do releases that fully remove the deprecated feature from their code base. The releases for these SDKs should have a clear Removed header to specify exactly what features were removed. In my mind, this should be all that's needed, because plenty of announcements and documentation have been provided by this point to explain migrations and reasonings.

Step Actions

1. At specified times before the removal, create announcements of the to-be-removed status of the deprecated feature.
2. SDK maintainers and contributors work to remove the deprecated feature from their code bases, as well as anything remaining in documentation, examples, etc.
3. The removal is merged as a part of a release for that SDK.
4. The SDK no longer containing the deprecated feature is released, as well as release notes and documentation noting the removal.

There are still some details I think to be ironed-out and I'm sure some steps I missed, but again just looking to get the conversation started.

[SimiHunjan]

Feature Removal Date: what is the date the deprecated feature will be removed? It might be easier to just remove all deprecated features every major release, but we could also choose to remove a deprecated feature after, say, 6 months? Or another specified amount of time. This could also mean, instead of removal, when support for a deprecated feature will cease. This should be clearly communicated. If a date is selected, it should be tracked in the deprecation doc. I vote for just the removal of them every major release, but am open to discussion on this.

If we want to adhere to semver guidelines, we would remove the deprecated feature when we move to the next major version. We should review these guidelines here to contribute to this discussion. https://semver.org/

How should I handle deprecating functionality?
Deprecating existing functionality is a normal part of software development and is often required to make forward progress. When you deprecate part of your public API, you should do two things: (1) update your documentation to let users know about the change, (2) issue a new minor release with the deprecation in place. 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.

[rwalworth]

Yes I am okay with semver versioning! Mostly just included the extra feature removal stuff here in case that wasn't desired for whatever reason. If we remove deprecated features only on major version updates, that helps simplify things and is less information that needs to be disseminated to the community.