Next Version Update

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 and 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:

# 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:

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:

# 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:

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:

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

5. Create Feature Branch

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:

PYLINT_VERSION = "{OLD_NEXT_PYLINT_VERSION}"

In eng/tools/azure-sdk-tools/azpysdk/mypy.py:

MYPY_VERSION = "{OLD_NEXT_MYPY_VERSION}"

In eng/tools/azure-sdk-tools/azpysdk/pyright.py:

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:

   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:

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:

| 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:

cd sdk/core/azure-core
azpysdk apistub .

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

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:

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 repository:

1. Clone azure-sdk-tools and create a feature branch:

   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:

   cd tools/apiview/parsers/python
   pip install -e . && pytest tests/
   

5. Commit and create PR:

   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 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):

   gh repo fork microsoft/typespec --clone
   cd typespec
   

2. Install Rush (TypeSpec uses Rush for monorepo management):

   npm install -g @microsoft/rush
   

3. Create a feature branch that names all tools being updated:

   # 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):

   # 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):

   # 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):

   # 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:

   rush update
   

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

   rush build
   

7. Run the type-checking and lint checks to confirm there are no new errors:

   rush check-format
   rush lint
   

8. Commit and push the changes:

   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:

   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.