Automate the update of client library README to reflect deprecated status
- Dominant language
- C#
- Stars
- 135
- Forks
- 260
- Avg merge
- 3d 1h
- Merged PRs (30d)
- 143
Description
GOALS: When marking packages as deprecated, enforce inclusion in the CSV files of a replacement library link, migration guide, deprecation date, and (for deprecated packages not undergoing a name change) minimum supported version. Automatically update the README to reflect deprecation of the library using values populated in the CSV files.
*Abstract:*
When a package is deprecated, the associated client library’s README file in GitHub should be updated to reflect the new deprecated status. A preformatted message advertising the deprecated status should be prominently added at the top of the file.
Unfortunately, this step is often forgotten. Even if the message is added, the updated README file often doesn’t get published to docs.microsoft.com. Publishing to docs.microsoft.com after the fact would require shipping a new version of the package.
I would like to see the process of updating the README when a package is deprecated to be automated, based on updates to the package CSV files.
*Requirements:*
- [x] 1) When packages are marked as deprecated in the CSV files via PRs there should be checks that verify a replacement library and migration guide have been listed for the deprecated package(s). The automation should also check that a deprecation date has been added and that the format of the migration guide link adheres to the following convention:
“aka.ms/azsdk/\/migrate/\”
UPDATE - we decided not to enforce the format as a hard requirement. Instead, we will make it a suggestion. The PR I submitted reflects this decision.
- [x] 2) If the package name remains the same, then the replacement library field should be filled in to match the deprecated library name. There should be no case where a deprecation update PR is submitted without a replacement library name. If the two names are equivalent, indicating the name hasn't changed, then the check for the migration guide can be skipped or marked as 'pass'. ~~If the two names are equivalent, then the automation should check for a 'version number' that represents the point of deprecation. In other words, all libs from version x.y.z and below are deprecated. If the version number field is not part of the CSV today, then it needs to be added.~~ Instead of checking for a version number we will suggest that the user update to the most recent package in order to avoid adding a new field to the CSV files.
- [x] 3) If the links for the replacement library and migration guide are not provided, or if any of the other checks fail, the PR should be rejected, and the submitter informed of the requirements.
- [x] 4) If the checks succeed, the automation should update the commit (or file a new commit) with an update to the ~~README~~ package manager that includes one of the following two messages, with standardized wording for packages with different names (top) and packages with the same name (bottom).
> **~~README~~ package manager update for packages with different names:**
Please note, this package has been deprecated. A replacement package is available \[package name\](link to replacement package) as of [date-MM/YY]. We strongly encourage you to upgrade to continue receiving updates. See \[Migration Guide\](aka.ms/azsdk//migrate/) for guidance on upgrading. Refer to our \[deprecation policy\](https://azure.github.io/azure-sdk/policies_support.html) for more details.
> **README update for packages with the same name:**
Please note, older versions of this package have been deprecated as of [date-MM-YY]. We strongly encourage you to upgrade to the latest version to continue receiving updates. Refer to our \[deprecation policy\](https://azure.github.io/azure-sdk/policies_support.html) for more details.
- [x] 5) The 'link to replacement package', and 'Migration Guide' links should be pulled from the relevant fields in the CSV file in the PR that triggered this automation.
Contributor guide
Assessment
This issue has not been assessed yet.