Azure / Azure/azure-sdk-for-net

docs(conversations-authoring): Add MigrationGuide and fix broken README links

Open
#57,786 1 comment 0 reactions 0 assignees View on GitHub
Client Cognitive - Language Service Attention
Dominant language
C#
Stars
6.1k
Forks
5.2k
Avg merge
1d 16h
Merged PRs (30d)
407

Description

## Summary

Addresses documentation gaps in the `Azure.AI.Language.Conversations.Authoring` package following the TypeSpec emitter migration.

## Changes

### 🆕 New: `MigrationGuide.md`
The README referenced a `MigrationGuide.md` ([source_migration] link) that did not exist — a broken link and an unmet documentation promise. This file is now created and covers:

- **Method renames** when upgrading from 1.0.0-beta.2 to 1.0.0-beta.3:
- `AssignDeploymentResources` → `AssignProjectResources`
- `UnassignDeploymentResources` → `UnassignProjectResources`
- `GetAssignDeploymentResourcesStatus` → `GetAssignProjectResourcesStatus`
- `GetUnassignDeploymentResourcesStatus` → `GetUnassignProjectResourcesStatus`
- **Parameter/return type changes** for `DeleteDeploymentFromResources`, `UnassignProjectResources`, and status methods
- **`CreateProject` API change**: `projectName` is now required in `ConversationAuthoringCreateProjectDetails`

Each breaking change includes before/after code examples to guide users through the upgrade.

### 🔧 Fix: `README.md` broken links
Two link definitions at the bottom of `README.md` were incomplete:
- `[package]` pointed to `(www.nuget.org/redacted) (missing package name) → fixed to `(www.nuget.org/redacted)
- `[text_refdocs]` pointed to `(learn.microsoft.com/redacted) (no specific path) → fixed to `(learn.microsoft.com/redacted)

### 🔧 Fix: `Sample21_ConversationsAuthoring_ListProjectResources.md` incorrect method names
The prose in this sample incorrectly referred to `GetProjectResources` / `GetProjectResourcesAsync` (a name from the beta.3 CHANGELOG plan that was not implemented). The actual API method is `GetDeploymentResources` / `GetDeploymentResourcesAsync`. The code snippets were already correct — only the surrounding text was wrong.

## Affected files
- `sdk/cognitivelanguage/Azure.AI.Language.Conversations.Authoring/MigrationGuide.md` (new)
- `sdk/cognitivelanguage/Azure.AI.Language.Conversations.Authoring/README.md` (modified)
- `sdk/cognitivelanguage/Azure.AI.Language.Conversations.Authoring/samples/Sample21_ConversationsAuthoring_ListProjectResources.md` (modified)

## Reviewers
cc `@ahmedaashour` `@bidisha-c` `@mikaelsitruk` `@quentinRobinson` `@sarkar-rajarshi`

> Generated by [Update Docs](https://github.com/Azure/azure-sdk-for-net/actions/runs/23959427373/agentic_workflow) · [◷](https://github.com/search?q=repo%3AAzure%2Fazure-sdk-for-net+%22gh-aw-workflow-id%3A+update-samples-and-docs%22&type=pullrequests)

---

> [!NOTE]
> This was originally intended as a pull request, but GitHub Actions is not permitted to create or approve pull requests in this repository.
> The changes have been pushed to branch `docs/conversations-authoring-migration-guide-2e88722587ea1af7`.
>
> **[Click here to create the pull request](https://github.com/Azure/azure-sdk-for-net/compare/main...docs/conversations-authoring-migration-guide-2e88722587ea1af7?expand=1&title=docs(conversations-authoring)%3A%20Add%20MigrationGuide%20and%20fix%20broken%20README%20links)**

To fix the permissions issue, go to **Settings** → **Actions** → **General** and enable **Allow GitHub Actions to create and approve pull requests**. See also: [gh-aw FAQ](https://github.github.com/gh-aw/reference/faq/#why-is-my-create-pull-request-workflow-failing-with-github-actions-is-not-permitted-to-create-or-approve-pull-requests)

Show patch preview (250 of 250 lines)

```diff
From 2b2e12c08e1006ef4cb6efbe1d28328d147a8dfc Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
Date: Fri, 3 Apr 2026 19:52:53 +0000
Subject: [PATCH] docs(conversations-authoring): add MigrationGuide and fix
README links

- Create MigrationGuide.md covering breaking changes from 1.0.0-beta.2 to 1.0.0-beta.3
(method renames, parameter type changes, CreateProject API change)
- Fix incomplete NuGet package link in README.md
- Fix incomplete API reference docs link in README.md
- Fix incorrect method names in Sample21 prose (GetProjectResources -> GetDeploymentResources)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
.../MigrationGuide.md | 183 ++++++++++++++++++
.../README.md | 4 +-
...ersationsAuthoring_ListProjectResources.md | 4 +-
3 files changed, 187 insertions(+), 4 deletions(-)
create mode 100644 sdk/cognitivelanguage/Azure.AI.Language.Conversations.Authoring/MigrationGuide.md

diff --git a/sdk/cognitivelanguage/Azure.AI.Language.Conversations.Authoring/MigrationGuide.md b/sdk/cognitivelanguage/Azure.AI.Language.Conversations.Authoring/MigrationGuide.md
new file mode 100644
index 000000000..32ef28eec
--- /dev/null
+++ b/sdk/cognitivelanguage/Azure.AI.Language.Conversations.Authoring/MigrationGuide.md
@@ -0,0 +1,183 @@
+# Migration Guide: Azure.AI.Language.Conversations.Authoring
+
+This guide helps developers migrate between versions of the `Azure.AI.Language.Conversations.Authoring` client library.
+
+## Table of contents
+
+- [Migrating from 1.0.0-beta.2 to 1.0.0-beta.3](#migrating-from-100-beta2-to-100-beta3)
+ - [Method renames for project resource operations](#method-renames-for-project-resource-operations)
+ - [Parameter type changes](#parameter-type-changes)
+ - [CreateProject now requires projectName in details](#createproject-now-requires-projectname-in-details)
+
+---
+
+## Migrating from 1.0.0-beta.2 to 1.
... (truncated)
```

Contributor guide

Open the contributing guide

Research direction

Review the proposed changes in sdk/cognitivelanguage/Azure.AI.Language.Conversations.Authoring/MigrationGuide.md, README.md, and samples/Sample21_ConversationsAuthoring_ListProjectResources.md. Verify the migration examples and API names against the package's existing documentation, then check that the README links resolve. Done means the guide exists, both links are complete, and the sample prose uses the implemented resource methods.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.