Update setup guide with post-setup requirements and fixes; fix test install order

Author: RyAuld

.Pipelines/ADO-PUBLISH-SETUP.md

@@ -25,8 +25,8 @@ Every publish requires explicitly entering a version and selecting a destination
 | **Validate** | always | asserts `packageVersion` matches `msal/sku.py` |
 | **CI** (tests on Py 3.9–3.13) | after Validate | — |
 | **Build** (sdist + wheel) | after CI | dist artifact |
-| **PublishMSALPython** | `publishTarget = MSAL-Python` | test.pypi.org |
-| **PublishPyPI** | `publishTarget = pypi` | PyPI (production) |
+| **PublishMSALPython** | `publishTarget = test.pypi.org (Preview / RC)` | test.pypi.org |
+| **PublishPyPI** | `publishTarget = pypi.org (Production)` | PyPI (production) |
 
 ---
 
@@ -46,11 +46,16 @@ Every publish requires explicitly entering a version and selecting a destination
 
 1. In your ADO project go to **Project Settings → Service connections → New service connection**.
 2. Choose **GitHub** and click **Next**.
-3. Select **GitHub App** (recommended) or **Personal Access Token**.
-   - GitHub App: follow the OAuth flow to install the ADO GitHub App on the
-     `AzureAD` organization and grant repository access to
-     `microsoft-authentication-library-for-python`.
-   - PAT: create a GitHub PAT with `repo` scope and paste it here.
+3. Under **Authentication**, select **Grant authorization** (OAuth) — do **not** use Personal Access Token.
+   - Click **Authorize** — a GitHub OAuth popup will open.
+   - Sign in with a GitHub account that has admin rights on the `AzureAD` organization.
+   - Grant access to `microsoft-authentication-library-for-python`.
+   - This installs the Azure Pipelines GitHub App and enables webhook and repository listing.
+
+   > **Why OAuth and not PAT:** PAT-based connections cannot install the GitHub webhook
+   > required for pipeline creation via CLI or API. The OAuth/GitHub App flow installs the
+   > webhook using the browser's authenticated GitHub session.
+
 4. Set **Service connection name**: `github-msal-python`
 5. Check **Grant access permission to all pipelines**, click **Save**.
 
@@ -70,8 +75,8 @@ for external registries.
    |-------|-------|
    | **Twine repository URL** | `https://test.pypi.org/legacy/` |
    | **EndpointName** (`-r` value) | `MSAL-Test-Python-Upload` |
-   | **Username** | `__token__` |
-   | **Password** | *(your test.pypi.org API token, e.g. `pypi-AgA...`)* |
+   | **Authentication method** | **Authentication Token** |
+   | **Token** | *(your test.pypi.org API token, full value including `pypi-` prefix)* |
    | **Service connection name** | `MSAL-Test-Python-Upload` |
 4. Check **Grant access permission to all pipelines**, click **Save**.
 
@@ -84,8 +89,8 @@ for external registries.
    |-------|-------|
    | **Twine repository URL** | `https://upload.pypi.org/legacy/` |
    | **EndpointName** (`-r` value) | `MSAL-Prod-Python-Upload` |
-   | **Username** | `__token__` |
-   | **Password** | *(your PyPI API token)* |
+   | **Authentication method** | **Authentication Token** |
+   | **Token** | *(your PyPI API token, full value including `pypi-` prefix)* |
    | **Service connection name** | `MSAL-Prod-Python-Upload` |
 4. Check **Grant access permission to all pipelines**, click **Save**.
 
@@ -151,29 +156,36 @@ This pipeline is **always manually queued**. Both fields are required — the Va
 
 | Parameter | Required | Description | Example values |
 |-----------|----------|-------------|----------------|
-| **Package version to publish** | ✅ Yes | Must exactly match `msal/sku.py __version__`. | `1.36.0` (release), `1.36.0rc1` (preview) |
-| **Publish target** | ✅ Yes | Explicit destination — no auto-routing. | `MSAL-Python` (test.pypi.org) or `pypi` (production) |
+| **Package version to publish** | Yes | Must exactly match `msal/sku.py __version__`. PEP 440 format only — no `-Preview` suffix. | `1.36.0` (release), `1.36.0rc1` (RC), `1.36.0b1` (beta) |
+| **Publish target** | Yes | Explicit destination — no auto-routing. | `test.pypi.org (Preview / RC)` or `pypi.org (Production)` |
+
+> **Version format:** PyPI enforces [PEP 440](https://peps.python.org/pep-0440/). Versions with `-` (e.g. `1.36.0-Preview`) are rejected. Use `rc1`, `b1`, or `a1` suffixes instead.
+
+> **Version must be in sync:** Before queuing, update `msal/sku.py __version__` to the target version and push the change. The Validate stage checks the value on the branch the run is sourced from, not the pipeline default branch.
 
 ---
 
 ## Step 8 — End-to-End Release Walkthrough
 
 ### Publishing a preview / release candidate to test.pypi.org
 
-1. Set `msal/sku.py __version__ = "1.36.0rc1"`
-2. Go to **Pipelines → Run pipeline**
-3. Enter `packageVersion = 1.36.0rc1`, select `publishTarget = MSAL-Python`
-4. Click **Run** — pipeline runs: Validate → CI → Build → PublishMSALPython
-5. Verify at <https://test.pypi.org/project/msal/>
+1. Set `msal/sku.py __version__ = "1.36.0rc1"` and push the change
+2. Go to **Pipelines → MSAL-Python · Publish → Run pipeline**
+3. Select the branch/tag to run from (e.g. the release branch)
+4. Enter **Package version to publish**: `1.36.0rc1`
+5. Select **Publish target**: `test.pypi.org (Preview / RC)`
+6. Click **Run** — pipeline runs: Validate → CI → Build → Publish to test.pypi.org
+7. Verify at <https://test.pypi.org/project/msal/>
 
 ### Publishing a production release to PyPI
 
-1. Set `msal/sku.py __version__ = "1.36.0"` and merge to the release branch
-2. Go to **Pipelines → Run pipeline**
-3. Enter `packageVersion = 1.36.0`, select `publishTarget = pypi`
-4. Click **Run** — pipeline runs: Validate → CI → Build → PublishPyPI (approval gate)
-5. Go to **Pipelines → Environments → MSAL-Python-Release** and approve the deployment
-6. Verify: `pip install msal==1.36.0` or check <https://pypi.org/project/msal/>
+1. Set `msal/sku.py __version__ = "1.36.0"` and push to the release branch
+2. Go to **Pipelines → MSAL-Python · Publish → Run pipeline**
+3. Select the release branch
+4. Enter **Package version to publish**: `1.36.0`
+5. Select **Publish target**: `pypi.org (Production)`
+6. Click **Run** — pipeline runs: Validate → CI → Build → Publish to PyPI (Production)
+7. Verify: `pip install msal==1.36.0` or check <https://pypi.org/project/msal/>
 
 ## Pipeline Trigger Reference
 
@@ -189,13 +201,30 @@ Manual queue (publishTarget = pypi)
 
 ---
 
+## Known Requirements
+
+The following requirements were identified during initial setup and testing:
+
+- The GitHub service connection **must** be created via OAuth (Grant authorization) in the ADO UI, not via CLI or PAT. The CLI `az pipelines create` command requires webhook installation on the GitHub repo, which requires org admin rights not available to service accounts.
+- The pipeline **must** be created via the ADO REST API (`/_apis/build/definitions`) or UI — not via `az pipelines create` — when using an OAuth GitHub service connection without org-level admin rights.
+- The `msal/sku.py __version__` must be updated and pushed to the source branch **before** the pipeline run is queued. The Validate stage reads the file from the checked-out branch at runtime.
+- The `requirements.txt` file includes `-e .` which causes pip to install `msal` from PyPI as a transitive dependency of `azure-identity`, overwriting the local editable install. The template handles this by removing the `-e .` line and reinstalling the local package last with `--no-deps`.
+- The `1.35.1` version bump (hotfix) was released from `origin/release-1.35.0` and was never merged back into `dev`. Before the next release from `dev`, this should be backfilled via PR: `https://github.com/AzureAD/microsoft-authentication-library-for-python/compare/dev...release-1.35.0`
+
+---
+
 ## Troubleshooting
 
 | Symptom | Likely cause | Fix |
 |---------|-------------|-----|
 | `403` on twine upload | Token expired or wrong scope | Regenerate API token on pypi.org; update the service connection |
 | `File already exists` error | Version already published; PyPI does not allow overwriting | Bump version in `msal/sku.py` |
-| Pipeline not triggered by tag | ADO only picks up tags after the pipeline is saved with the `tags:` trigger | Re-save the pipeline in ADO after adding the trigger |
+| Validate stage: `msal/sku.py ''` (empty version) | Python import silently failed | The template uses `grep`/`sed` to read the version — verify `msal/sku.py` contains a `__version__ = "..."` line |
+| Validate stage: version mismatch | `sku.py` on the source branch doesn't match the parameter entered | Update `msal/sku.py` on the branch the run is sourced from, not just the pipeline default branch |
+| Tests: collection failure across all modules | PyPI `msal` installed over the local editable install | Ensure the template installs local package last with `--no-deps` |
+| `az pipelines create` fails with webhook error | GitHub service connection PAT/account lacks org admin rights | Create the pipeline via the ADO UI using a browser session with org admin GitHub access |
+| Pipeline creation fails: `Value cannot be null. Parameter name: Connection` | GitHub SC ID is wrong or SC was recreated | Re-query the SC ID with `az devops service-endpoint list` and use the current ID |
+| Service connection shows `Authentication: PersonalAccessToken` | SC was created via CLI with a PAT | Delete and recreate via UI using OAuth (Grant authorization) so repos are enumerable |
 | `TwineAuthenticate` says endpoint not found | Service connection name mismatch | Ensure `pythonUploadServiceConnection` value exactly matches the service connection name |
 
 ---

.Pipelines/pipeline-publish.yml

@@ -42,7 +42,7 @@ variables:
 # ══════════════════════════════════════════════════════════════════════════════
 stages:
 - stage: Validate
-  displayName: '🔍 Validate version'
+  displayName: 'Validate version'
   jobs:
   - job: ValidateVersion
     displayName: 'Check version matches source'
@@ -74,7 +74,7 @@ stages:
 # Stage 2 · CI — run the full test matrix
 # ══════════════════════════════════════════════════════════════════════════════
 - stage: CI
-  displayName: '🧪 Run tests'
+  displayName: 'Run tests'
   dependsOn: Validate
   condition: succeeded()
   jobs:
@@ -101,7 +101,7 @@ stages:
 # Stage 3 · Build — compile sdist + wheel (single Python version)
 # ══════════════════════════════════════════════════════════════════════════════
 - stage: Build
-  displayName: '📦 Build package'
+  displayName: 'Build package'
   dependsOn: CI
   condition: succeeded()
   jobs:
@@ -120,7 +120,7 @@ stages:
 #   Runs when: publishTarget == 'MSAL-Python'
 # ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════
 - stage: PublishMSALPython
-  displayName: '🚀 Publish to test.pypi.org (Preview)'
+  displayName: 'Publish to test.pypi.org (Preview)'
   dependsOn: Build
   condition: >
     and(
@@ -151,7 +151,7 @@ stages:
 #   Runs when: publishTarget == 'pypi'
 # ══════════════════════════════════════════════════════════════════════════════
 - stage: PublishPyPI
-  displayName: '🚀 Publish to PyPI (Production)'
+  displayName: 'Publish to PyPI (Production)'
   dependsOn: Build
   condition: >
     and(

.Pipelines/template-run-tests.yml

@@ -17,8 +17,8 @@ steps:
 
 - script: |
     python -m pip install --upgrade pip
-    pip install -e .
     grep -v '^-e' requirements.txt | pip install -r /dev/stdin
+    pip install -e . --no-deps
   displayName: 'Install dependencies'
 
 # Use bash: (not script:) so set -o pipefail works — script: uses /bin/sh on Linux