# Next Version Update

> Automate promoting next-* tool versions (pylint, mypy, pyright) to become the current pinned versions in azure-sdk-for-python. Use this skill when the weekly next-* CI checks are passing and you want to update the pinned tool versions for all packages.

- Skill: `azure-azure-sdk-for-python/next-version-update` (Agent Skill)
- Install (CLI): `npx skillmds@latest add azure-azure-sdk-for-python/next-version-update`
- Raw SKILL.md: https://api.skillmd.com/api/skills/azure-azure-sdk-for-python/next-version-update/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: Azure (https://skillmd.com/u/azure-azure-sdk-for-python)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/azure-azure-sdk-for-python/next-version-update

---


<!-- cspell:words pylintrc vnext -->

# Next Version Update

Promote `next-*` tool versions (pylint, mypy, pyright) to become the current pinned versions, update all relevant configuration files, and set new next-* targets for tracking upcoming releases.

## Overview

The repository pins specific versions of pylint, mypy, and pyright and runs weekly `next-*` jobs to proactively detect compatibility issues with upcoming versions. When CI confirms the next-* versions are clean, this skill promotes them to become the current pinned versions.

> **Required cross-repo check (do not skip):** After updating `azure-sdk-for-python`, you must also check whether matching updates are required in **both** [azure-sdk-tools](https://github.com/Azure/azure-sdk-tools) and [Microsoft/TypeSpec](https://github.com/microsoft/typespec). Treat the version bump as complete only after those repositories are reviewed and, when needed, PRs are opened.

Files updated in **azure-sdk-for-python**:
- `eng/tools/azure-sdk-tools/azpysdk/pylint.py` – `PYLINT_VERSION` constant
- `eng/tools/azure-sdk-tools/azpysdk/mypy.py` – `MYPY_VERSION` constant
- `eng/tools/azure-sdk-tools/azpysdk/pyright.py` – `PYRIGHT_VERSION` constant
- `pylintrc` – root pylintrc used by the current pylint version
- `eng/pylintrc` – pylintrc used by the `next-pylint` job (update for new next version)
- `doc/analyze_check_versions.md` – version table documentation

Files updated in **azure-sdk-tools** (separate PR):
- `tools/apiview/parsers/python/apistubgen/pylintrc` – pylintrc for apiview stub generator
- `tools/apiview/parsers/python/apistubgen/requirements.txt` – pylint version pin for apiview stub generator

Files updated in **Microsoft/TypeSpec** (separate PR, for any pylint/mypy/pyright version update):
- `packages/compiler/package.json` or emitter-specific `package.json` – pyright version pin used by the TypeSpec compiler and emitters
- Any Python-based tooling configuration files that reference pylint or mypy versions

## Prerequisites

Verify the following before running:

```bash
# Check Python is available
python --version

# Check pip is available
pip --version

# Check GitHub CLI
gh --version
```

## Workflow

### 1. Verify Next-Version CI Is Passing

Before promoting, confirm the next-* weekly analyze jobs have passed for the `http-client-python` (in Microsoft/TypeSpec repo) service and other core (azure-sdk-for-python azure-core/corehttp/azure-mgmt-core) packages. 

Check the Azure DevOps pipeline named **"python - corehttp - tests-weekly"** or similar weekly analyze pipelines. All three of the following jobs must pass (or only have pre-existing failures that are tracked):

- **Run Pylint Next** (uses `azpysdk next-pylint`)
- **Run MyPy Next** (uses `azpysdk next-mypy`)
- **Run Pyright Next** (uses `azpysdk next-pyright`)

Also verify via GitHub issues: the vnext issue creator creates/closes issues per-package. Check that there are no open `next-pylint`, `next-mypy`, or `next-pyright` issues for the core packages.

### 2. Read Current Next Versions

Read the current next-* versions from `doc/analyze_check_versions.md`:

```bash
grep -E "VERSION" eng/tools/azure-sdk-tools/azpysdk/pylint.py eng/tools/azure-sdk-tools/azpysdk/mypy.py eng/tools/azure-sdk-tools/azpysdk/pyright.py
```

Note the **Next Version** values for pylint, mypy, and pyright. These are the versions being promoted to current.

### 3. Determine New Next Versions

Look up the latest available versions on PyPI to set as the new next-* targets:

```bash
# Get latest pylint version
pip index versions pylint 2>/dev/null | head -1

# Get latest mypy version
pip index versions mypy 2>/dev/null | head -1

# Get latest pyright version
pip index versions pyright 2>/dev/null | head -1
```

If `pip index` is unavailable, use:
```bash
pip install pylint== 2>&1 | grep "from versions"
pip install mypy== 2>&1 | grep "from versions"
pip install pyright== 2>&1 | grep "from versions"
```

### 4. Prepare Repository

Reset and sync the SDK repo to a clean state:

```bash
git reset HEAD && git checkout . && git clean -fd && git checkout origin/main && git pull origin main
```

### 5. Create Feature Branch

```bash
git checkout -b bump-next-versions-{YYYYMMDD}
```

Replace `{YYYYMMDD}` with today's date (e.g., `bump-next-versions-20260420`).

### 6. Update `azpysdk` Python Constants

Update the version constants used by the azpysdk CLI:

In `eng/tools/azure-sdk-tools/azpysdk/pylint.py`:
```python
PYLINT_VERSION = "{OLD_NEXT_PYLINT_VERSION}"
```

In `eng/tools/azure-sdk-tools/azpysdk/mypy.py`:
```python
MYPY_VERSION = "{OLD_NEXT_MYPY_VERSION}"
```

In `eng/tools/azure-sdk-tools/azpysdk/pyright.py`:
```python
PYRIGHT_VERSION = "{OLD_NEXT_PYRIGHT_VERSION}"
```

### 7. Update `pylintrc` Files

When pylint's **version** changes, the root `pylintrc` and `eng/pylintrc` may need to be updated to disable new warnings or enable newly-available rules.

**For a major version bump:**

1. Check the pylint changelog for new/renamed rules that affect the codebase.
2. Update `pylintrc` (root) by copying the content from `eng/pylintrc`:
   ```bash
   cp eng/pylintrc pylintrc
   ```
3. Update `eng/pylintrc` for the new next-pylint version:
   - Add any new rules that need to be disabled for the next version.
   - Refer to pylint's changelog: `https://pylint.readthedocs.io/en/stable/whatsnew/`

**For a minor/patch version bump:** Typically no pylintrc changes are needed, but verify by running:
```bash
cd sdk/core/corehttp
azpysdk next-pylint .
```

### 8. Update `doc/analyze_check_versions.md`

Update the version table to reflect the new pinned versions and next targets:

```markdown
| Tool | Current Version | Next Version | Next Version Merge Date |
|------|-----------------|--------------|-------------------------|
Pylint | {OLD_NEXT_PYLINT_VERSION} | {NEW_NEXT_PYLINT_VERSION} | {TARGET_DATE} |
MyPy | {OLD_NEXT_MYPY_VERSION} | {NEW_NEXT_MYPY_VERSION} | {TARGET_DATE} |
Pyright | {OLD_NEXT_PYRIGHT_VERSION} | {NEW_NEXT_PYRIGHT_VERSION} | {TARGET_DATE} |
```

The `{TARGET_DATE}` should be approximately 12 weeks from today (the date when the next-* versions would be merged if CI passes).

If there is no newer version available yet, use `N/A` for both **Next Version** and **Next Version Merge Date**.

### 9. Update `eng/apiview_reqs.txt`

Update the pylint version used by the apiview stub generator:

```
pylint=={OLD_NEXT_PYLINT_VERSION}
```

> **Note:** The `astroid` and related packages may also need version updates to be compatible with the new pylint version. Run the apistub check locally to verify:
> ```bash
> cd sdk/core/azure-core
> azpysdk apistub .
> ```

### 10. Commit Changes in azure-sdk-for-python

```bash
git add pylintrc eng/pylintrc \
        eng/tools/azure-sdk-tools/azpysdk/pylint.py \
        eng/tools/azure-sdk-tools/azpysdk/mypy.py \
        eng/tools/azure-sdk-tools/azpysdk/pyright.py \
        doc/analyze_check_versions.md \
        eng/apiview_reqs.txt
git commit -m "Promote next-* tool versions: pylint {OLD_NEXT_PYLINT_VERSION}, mypy {OLD_NEXT_MYPY_VERSION}, pyright {OLD_NEXT_PYRIGHT_VERSION}"
```

### 11. Create Pull Request in azure-sdk-for-python

Push branch and create PR:

```bash
git push -u origin bump-next-versions-{YYYYMMDD}
gh pr create \
  --title "Promote next-* tool versions: pylint {OLD_NEXT_PYLINT_VERSION}, mypy {OLD_NEXT_MYPY_VERSION}, pyright {OLD_NEXT_PYRIGHT_VERSION}" \
  --body "Promotes the next-* versions of pylint, mypy, and pyright to the current pinned versions after verifying the weekly CI jobs pass.

## Changes
- pylint: {OLD_PYLINT_VERSION} → {OLD_NEXT_PYLINT_VERSION} (next: {NEW_NEXT_PYLINT_VERSION})
- mypy: {OLD_MYPY_VERSION} → {OLD_NEXT_MYPY_VERSION} (next: {NEW_NEXT_MYPY_VERSION})
- pyright: {OLD_PYRIGHT_VERSION} → {OLD_NEXT_PYRIGHT_VERSION} (next: {NEW_NEXT_PYRIGHT_VERSION})

## Verification
- [ ] Weekly next-pylint CI passes for http-client-python
- [ ] Weekly next-mypy CI passes for http-client-python
- [ ] Weekly next-pyright CI passes for http-client-python
- [ ] Checked **azure-sdk-tools** for matching tool-version updates; opened PR if needed
- [ ] Checked **Microsoft/TypeSpec** for matching tool-version updates; opened PR if needed"
```

### 12. Update azure-sdk-tools Repository (Separate PR)

> **Required review:** Always review this repo for every run of this skill. A PR is required whenever the version bump affects apiview parser dependencies/config.

For a pylint **version** bump, create a separate PR in the [azure-sdk-tools](https://github.com/Azure/azure-sdk-tools) repository:

1. Clone azure-sdk-tools and create a feature branch:
   ```bash
   cd /path/to/azure-sdk-tools
   git checkout -b bump-apiview-pylint-{OLD_NEXT_PYLINT_VERSION}
   ```

2. Update the pylint version in the apiview stub generator requirements:
   - File: `tools/apiview/parsers/python/apistubgen/requirements.txt`
   - Change `pylint=={OLD_PYLINT_VERSION}` → `pylint=={OLD_NEXT_PYLINT_VERSION}`

3. Update the pylintrc for the apiview stub generator if needed:
   - File: `tools/apiview/parsers/python/apistubgen/pylintrc`
   - Add any new disable entries needed for the new pylint major version.

4. Run the apiview tests to verify:
   ```bash
   cd tools/apiview/parsers/python
   pip install -e . && pytest tests/
   ```

5. Commit and create PR:
   ```bash
   git add tools/apiview/parsers/python/apistubgen/
   git commit -m "bump apiview pylint to {OLD_NEXT_PYLINT_VERSION}"
   git push -u origin bump-apiview-pylint-{OLD_NEXT_PYLINT_VERSION}
   gh pr create --title "bump apiview pylint to {OLD_NEXT_PYLINT_VERSION}" \
     --body "Updates the pylint version used by the apiview stub generator from {OLD_PYLINT_VERSION} to {OLD_NEXT_PYLINT_VERSION}."
   ```

### 13. Update Microsoft/TypeSpec Repository (Separate PR)

> **Required review:** Always review this repo for every run of this skill. A PR is required whenever TypeSpec pins or tooling references the bumped versions.

For **any** next-* version update (pylint, mypy, or pyright), create a separate PR in the [Microsoft/TypeSpec](https://github.com/microsoft/typespec) repository to keep the tool versions aligned. TypeSpec uses pyright for type-checking its TypeScript packages and may reference pylint/mypy in Python-based tooling.

> **Before starting:** Read the TypeSpec contribution guidelines at https://github.com/microsoft/typespec/blob/main/CONTRIBUTING.md. Key requirements include signing the Microsoft CLA, running `rush update` after dependency changes, and ensuring `rush build` passes.

1. Fork and clone the TypeSpec repository (if not already done):
   ```bash
   gh repo fork microsoft/typespec --clone
   cd typespec
   ```

2. Install Rush (TypeSpec uses Rush for monorepo management):
   ```bash
   npm install -g @microsoft/rush
   ```

3. Create a feature branch that names all tools being updated:
   ```bash
   # Example for all three tools:
   git checkout -b bump-tool-versions-pylint-{OLD_NEXT_PYLINT_VERSION}-mypy-{OLD_NEXT_MYPY_VERSION}-pyright-{OLD_NEXT_PYRIGHT_VERSION}
   ```

4. Find all files that reference the tool versions and update them:

   **For pyright** (used across the TypeScript monorepo):
   ```bash
   # Find package.json files that pin pyright
   grep -r "\"pyright\"" --include="package.json" . | grep -v node_modules
   ```
   Update each occurrence from `{OLD_PYRIGHT_VERSION}` → `{OLD_NEXT_PYRIGHT_VERSION}`.

   **For pylint** (used in any Python tooling):
   ```bash
   # Find requirements files or pyproject.toml files that pin pylint
   grep -r "pylint==" --include="*.txt" --include="*.toml" --include="*.cfg" . | grep -v node_modules
   ```
   Update each occurrence from `{OLD_PYLINT_VERSION}` → `{OLD_NEXT_PYLINT_VERSION}`.

   **For mypy** (used in any Python tooling):
   ```bash
   # Find requirements files or pyproject.toml files that pin mypy
   grep -r "mypy==" --include="*.txt" --include="*.toml" --include="*.cfg" . | grep -v node_modules
   ```
   Update each occurrence from `{OLD_MYPY_VERSION}` → `{OLD_NEXT_MYPY_VERSION}`.

5. Run Rush update to regenerate the lockfile:
   ```bash
   rush update
   ```

6. Run Rush build to verify the update doesn't break anything:
   ```bash
   rush build
   ```

7. Run the type-checking and lint checks to confirm there are no new errors:
   ```bash
   rush check-format
   rush lint
   ```

8. Commit and push the changes:
   ```bash
   git add .
   git commit -m "bump tool versions: pylint {OLD_NEXT_PYLINT_VERSION}, mypy {OLD_NEXT_MYPY_VERSION}, pyright {OLD_NEXT_PYRIGHT_VERSION}"
   git push -u origin bump-tool-versions-pylint-{OLD_NEXT_PYLINT_VERSION}-mypy-{OLD_NEXT_MYPY_VERSION}-pyright-{OLD_NEXT_PYRIGHT_VERSION}
   ```

9. Create the pull request, following the TypeSpec PR template:
   ```bash
   gh pr create \
     --repo microsoft/typespec \
     --title "bump tool versions: pylint {OLD_NEXT_PYLINT_VERSION}, mypy {OLD_NEXT_MYPY_VERSION}, pyright {OLD_NEXT_PYRIGHT_VERSION}" \
     --body "Updates the pinned tool versions across the repo:
   - pylint: {OLD_PYLINT_VERSION} → {OLD_NEXT_PYLINT_VERSION}
   - mypy: {OLD_MYPY_VERSION} → {OLD_NEXT_MYPY_VERSION}
   - pyright: {OLD_PYRIGHT_VERSION} → {OLD_NEXT_PYRIGHT_VERSION}

   ## Checklist
   - [ ] I have signed the Microsoft CLA
   - [ ] \`rush update\` has been run
   - [ ] \`rush build\` passes
   - [ ] No new type or lint errors introduced"
   ```

10. Monitor the PR CI and address any new errors that surface in TypeSpec packages.

> **Note:** If only some tools are pinned in the TypeSpec repo (e.g., TypeSpec may only pin pyright and not pylint/mypy), skip the steps for tools that are not referenced. Check existing issues or PRs (search for `pylint`, `mypy`, `pyright` in open PRs) before opening duplicates.