Azure / Azure/azure-sdk

Fix broken links failing Verify Site CI on PRs #9736 and #9667

Open
#9,747 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
PowerShell
Stars
597
Forks
374
Avg merge
5d 21h
Merged PRs (30d)
42

Description

## Summary

The "Verify Site" CI check is failing on PRs #9736 and #9667 due to broken links on the generated site. **All of these broken links are pre-existing on `main`** — neither PR introduced them. They block CI for any PR that triggers a full site build.

This issue consolidates all broken links found across both CI runs with proposed fixes for each.

---

## Broken Links and Proposed Fixes

### 1. Azure.Identity release link — wrong ref prefix (`release/` branch vs tag)

**Broken URL:**
```
https://github.com/Azure/azure-sdk-for-net/blob/release/Azure.Identity_1.18.0/sdk/core/Azure.Core/src/docs/ConfigurationAndDependencyInjection.md
```
**Appears on:** `releases/2026-03/dotnet.html`

**Root cause:** The URL uses `blob/release/Azure.Identity_1.18.0` (a branch name that doesn't exist). The tag `Azure.Identity_1.18.0` exists but has no `release/` prefix.

**Fix:** Change `release/Azure.Identity_1.18.0` to `Azure.Identity_1.18.0` in the source YAML that generates this link.

**Correct URL:** `https://github.com/Azure/azure-sdk-for-net/blob/Azure.Identity_1.18.0/sdk/core/Azure.Core/src/docs/ConfigurationAndDependencyInjection.md`

---

### 2. Azure.AI.VoiceLive — wrong SDK subdirectory (`sdk/ai/` vs `sdk/voicelive/`)

**Broken URLs:**
```
https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.VoiceLive_1.0.0/sdk/ai/Azure.AI.VoiceLive/
https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.VoiceLive_1.0.0/sdk/ai/Azure.AI.VoiceLive/CHANGELOG.md
```
**Appears on:** `releases/latest/dotnet.html`, `releases/latest/all/dotnet.html`, `releases/latest/`, `releases/2025-10/dotnet.html`, `index.html`

**Root cause:** The package lives at `sdk/voicelive/Azure.AI.VoiceLive/`, not `sdk/ai/Azure.AI.VoiceLive/`. The `RepoPath` in `dotnet-packages.csv` likely has the wrong directory.

**Fix:** Update `RepoPath` in `_data/releases/latest/dotnet-packages.csv` from `sdk/ai/Azure.AI.VoiceLive/` to `sdk/voicelive/Azure.AI.VoiceLive/`.

**Correct URLs:**
- `https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.VoiceLive_1.0.0/sdk/voicelive/Azure.AI.VoiceLive/`
- `https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.VoiceLive_1.0.0/sdk/voicelive/Azure.AI.VoiceLive/CHANGELOG.md`

---

### 3. Packages.Data.props — file removed from azure-sdk-for-net

**Broken URL:**
```
https://github.com/Azure/azure-sdk-for-net/blob/main/eng/Packages.Data.props
```
**Appears on:** `dotnet_introduction.html`

**Root cause:** `eng/Packages.Data.props` was deleted from the azure-sdk-for-net repo. No direct replacement file exists at `eng/`.

**Fix:** Remove or replace the reference in the source markdown for `dotnet_introduction.html`. If the content it referenced (package listing data) is available elsewhere, link to that. Otherwise, remove the link entirely.

---

### 4. StorSimple MSDocs links — deprecated package docs removed (2 URLs)

**Broken URLs:**
```
https://learn.microsoft.com/javascript/api/overview/azure/arm-storsimple1200series-readme
https://learn.microsoft.com/javascript/api/overview/azure/arm-storsimple8000series-readme
```
**Appears on:** `releases/deprecated/js.html`, `releases/deprecated/index.html`

**Root cause:** Microsoft removed the API docs for these deprecated StorSimple JS packages. The MSDocs column in `js-packages.csv` may be empty (triggering auto-generation) or may contain these dead URLs.

**Fix:** Set `MSDocs="NA"` for `@azure/arm-storsimple1200series` and `@azure/arm-storsimple8000series` in `_data/releases/latest/js-packages.csv`. The "NA" value tells the template to skip MSDocs link generation (falls through to GHDocs). Note: the automated `Update-Release-Versions.ps1` pipeline may have already fixed this — verify the current CSV values before making changes.

---

### 5. Neon.Postgres (liftrneon) spec links — spec removed from azure-rest-api-specs (5 unique URLs)

**Broken URLs:**
```
https://github.com/Azure/azure-rest-api-specs/tree/main/specification/liftrneon/resource-manager
https://github.com/Azure/azure-rest-api-specs/tree/main/specification/liftrneon/resource-manager/Neon.Postgres/stable/2025-03-01
https://github.com/Azure/azure-rest-api-specs/tree/main/specification/liftrneon/resource-manager/Neon.Postgres/preview/2025-03-01-preview
https://github.com/Azure/azure-rest-api-specs/tree/main/specification/liftrneon/resource-manager/Neon.Postgres/preview/2024-12-22-preview
https://github.com/Azure/azure-rest-api-specs/tree/main/specification/liftrneon/resource-manager/Neon.Postgres/preview/2024-08-01-preview
```
**Appears on:** `releases/latest/all/specs.html`, `releases/latest/mgmt/specs.html`

**Root cause:** The `specification/liftrneon/` directory was entirely removed from the `main` branch of `Azure/azure-rest-api-specs`. The migration PR (azure-rest-api-specs#38484) was closed without merging. The spec no longer exists on `main`.

**Fix:** Remove the liftrneon entries from `_data/releases/latest/specs.csv`, or update their SpecPath to point to wherever the Neon.Postgres spec now lives. If the spec has been fully removed, delete these rows from specs.csv.

---

### 6. Compute spec links — old RP subdirectory names (4 unique URLs)

**Broken URLs:**
```
https://github.com/Azure/azure-rest-api-specs/tree/main/specification/compute/resource-manager/Microsoft.Compute/ComputeRP/stable/2024-11-01
https://github.com/Azure/azure-rest-api-specs/tree/main/specification/compute/resource-manager/Microsoft.Compute/DiskRP/stable/2024-03-02
https://github.com/Azure/azure-rest-api-specs/tree/main/specification/compute/resource-manager/Microsoft.Compute/GalleryRP/stable/2024-03-03
https://github.com/Azure/azure-rest-api-specs/tree/main/specification/compute/resource-manager/Microsoft.Compute/RecommenderRP
```
**Appears on:** `releases/latest/mgmt/specs.html`

**Root cause:** The azure-rest-api-specs repo restructured the Compute spec directories. The old names (`ComputeRP`, `DiskRP`, `GalleryRP`, `RecommenderRP`) were replaced with new names (`Compute`, `Compute`, `Compute`, `Recommender`). DiskRP and GalleryRP API versions are now consolidated under the `Compute` directory.

**Fix:** These broken links appear to be generated by the spec page template rather than stored literally in specs.csv (which already uses correct paths). Investigate the template logic in `_includes/` that constructs spec GitHub URLs. If the URLs are derived from other CSV columns or computed differently than the SpecPath column, update accordingly.

| Old (broken) path | Correct path |
|---|---|
| `Microsoft.Compute/ComputeRP/stable/2024-11-01` | `Microsoft.Compute/Compute/stable/2024-11-01` |
| `Microsoft.Compute/DiskRP/stable/2024-03-02` | `Microsoft.Compute/Compute/stable/2024-03-02` |
| `Microsoft.Compute/GalleryRP/stable/2024-03-03` | `Microsoft.Compute/Compute/stable/2024-03-03` |
| `Microsoft.Compute/RecommenderRP` | `Microsoft.Compute/Recommender` |

---

### 7. KeyVault spec links — missing nested subdirectory (2 unique URLs)

**Broken URLs:**
```
https://github.com/Azure/azure-rest-api-specs/tree/main/specification/keyvault/resource-manager/Microsoft.KeyVault/stable/2025-05-01
https://github.com/Azure/azure-rest-api-specs/tree/main/specification/keyvault/resource-manager/Microsoft.KeyVault/preview/2026-03-01-preview
```
**Appears on:** `releases/latest/mgmt/specs.html`

**Root cause:** Same TypeSpec restructuring issue. The KeyVault spec moved from `Microsoft.KeyVault/stable/` to `Microsoft.KeyVault/KeyVault/stable/`. The specs.csv already has the correct paths, so this is a template generation issue.

| Old (broken) path | Correct path |
|---|---|
| `Microsoft.KeyVault/stable/2025-05-01` | `Microsoft.KeyVault/KeyVault/stable/2025-05-01` |
| `Microsoft.KeyVault/preview/2026-03-01-preview` | `Microsoft.KeyVault/KeyVault/preview/2026-03-01-preview` |

---

### 8. Marketplace Catalog spec links — wrong namespace (2 unique URLs)

**Broken URLs:**
```
https://github.com/Azure/azure-rest-api-specs/tree/main/specification/marketplacecatalog/resource-manager/Microsoft.Products/Products
https://github.com/Azure/azure-rest-api-specs/tree/main/specification/marketplacecatalog/resource-manager/Microsoft.Reviews/Reviews/preview/2023-01-01-preview
```
**Appears on:** `releases/latest/mgmt/specs.html`

**Root cause:** The specs use namespace `Microsoft.Marketplace` but the generated links use `Microsoft.Products` and `Microsoft.Reviews`. Same template generation issue.

| Old (broken) path | Correct path |
|---|---|
| `Microsoft.Products/Products` | `Microsoft.Marketplace/Products` |
| `Microsoft.Reviews/Reviews/preview/2023-01-01-preview` | `Microsoft.Marketplace/Reviews/preview/2023-01-01-preview` |

---

## Notes

- **All broken links are pre-existing on `main`** — they affect any PR that triggers a full site build.
- For spec links (categories 5-8), the `specs.csv` data appears correct, but the generated URLs are wrong. The spec page template logic should be investigated to determine how it constructs GitHub URLs from the CSV data.
- The correct approach for each broken link is to find and use the valid URL. Only use "NA" when no valid URL exists (e.g., deleted docs, removed specs).
- References: #9736, #9667

Contributor guide

Open the contributing guide

Research direction

Start by running the Verify Site CI check and inspect the generated pages listed in the issue. Review _data/releases/latest/dotnet-packages.csv, js-packages.csv, specs.csv, the source markdown for dotnet_introduction.html, and the relevant _includes/ templates. Done means every listed broken link is corrected or intentionally removed and the full site verification passes.

Written by the indexing model from the issue text.

Assessment

Domain
build-system, ci-cd, documentation, release
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.