.NET 8 → .NET 10 마이그레이션

.NET 8 → .NET 10 마이그레이션은(는) 무엇을 하나요?

이 스킬은 번들된 결정적 도구(scripts/dmig)를 실행하고 그 결과를 설명합니다. 항상 먼저 분석하고, 분석에서 승인된 그룹만 구현하세요. 분석기는 측정을 수행하며, 당신의 역할은 도구를 올바르게 실행하고, 결과를 읽고, 의미를 설명하는 것 — 도구가 확인할 수 없는 내용을 과장하지 않고 전달하는 것입니다.

분석이 먼저인 이유

모노레포에서 하나의 저장소는 거의 하나의 마이그레이션 단위가 아닙니다. net10.0으로 이동한 공유 라이브러리는 여전히 net8.0을 사용하는 모든 애플리케이션을 중단시키며, global.json이나 Directory.Packages.props 같은 파일은 모든 사람에게 영향을 줍니다. 따라서 분석은 전체 저장소를 매핑하고, 안전한 순서로 그룹을 제안하며, 실제 코드를 변경하기 전에 기준 및 일회용 실험을 통해 그 주장을 입증합니다. 구현은 나중에 승인된 그룹 단위로 수행됩니다.

실행 방법

1. 저장소 외부에 출력 폴더를 선택합니다 (도구는 저장소 내부를 거부합니다): 보고서, 로그, NuGet 메타데이터 캐시 및 임시 워크트리가 모두 이곳에 저장됩니다.

2. dotnet을 선택합니다. 도구는 사전 점검에서 SDK와 런타임을 자체적으로 확인합니다. 올바른 실행 파일을 가리키기만 하면 됩니다. 머신에 전용 dotnet 루트(SDK 10 + 런타임 8 공존)가 있는 경우 --dotnet 또는 DMIG_DOTNET으로 전달합니다. .NET 8이 다른 dotnet 폴더에 설치된 경우 도구가 일반적인 위치에서 찾거나, --dotnet-root <폴더> / DMIG_DOTNET_ROOTS에서 가져와 자체 폴더의 링크를 통해 SDK와 결합합니다 (설치가 변경되지 않음).

3. 두 라이브러리를 설치합니다 (누락된 경우, 조직의 Python 미러에서): python -m pip install -r requirements.txt (테스트: requirements-dev.txt도). 항상 python -m ...을 사용하세요: Scripts 폴더가 PATH에 없을 수 있습니다. sh, bash 또는 sed는 필요하지 않습니다.

4. 분석을 실행합니다 (Windows 경로도 PYTHONPATH, --repo, --out에서 작동하며, Git Bash에서도 가능):

   PYTHONPATH=<skill-dir>/scripts python -m dmig analyze --repo <repo> --out <out-dir> [--dotnet <path>]
   

   유용한 플래그: --offline (구성된 피드 조회 안 함), --no-baseline, --no-experiment, --environment contract.json (환경이 제공하는 외부 테스트 서비스 및 라이선스 도구), --request request.json (중립 요청, references/contracts.md 참조). 소규모 저장소는 약 1분; 대규모 모노레포는 자체 복원 + 빌드 + 테스트 시간만큼 두 배(기준 및 실험) 걸립니다. 하네스가 허용하는 경우 백그라운드에서 실행하고, 동일 저장소에서 동시에 두 번째 복사본을 시작하지 마십시오. 진행률은 stderr에 한 줄씩 표시됩니다([dmig hh:mm:ss] baseline …); stdout에는 최종 JSON 요약만 출력되며, 각 명령의 전체 로그는 완료 시 <out>/logs/에 나타납니다.

   설치할 필요 없음: 스킬 폴더에는 dmig.cmd (Windows)와 dmig (Linux/macOS) 시작 파일이 있으며, PYTHONPATH=<skill-dir>/scripts python -m dmig와 동일합니다. python -m dmig preflight ...는 환경 확인만 실행합니다(몇 초). 새 머신에서는 먼저 python -m dmig doctor <repo>를 실행하세요: 일반 언어로 된 준비 상태 체크리스트(doctor-report.md, environment-capabilities.json, 결과 READY / READY_WITH_LIMITATIONS / BLOCKED).

   단축 형식 (통합 이름): 모든 명령은 저장소를 첫 번째 인수로 받고 --out을 <repo>.dmig/<step>/으로, --plan을 <repo>.dmig/analysis/migration-plan.json으로 기본 설정합니다: dmig analyze <repo> --target net10.0, dmig migrate <repo> --group <id> (= implement), dmig validate <repo> --scope group|repository (--group <id>는 그룹용; repository = PHASE_7), dmig rollback <run folder> (실행의 일회용 복사본을 정리하고 패치를 취소하는 방법 출력). 각 migrate/global/validate 실행은 dmig-result.json(계약의 camelCase 결과)도 작성합니다. 패키지 미러: --package-catalog mirror.json (승인된 버전만 선택되며, 이후 단계에서 재사용).

   존중해야 할 기본값: 도구에는 자체 네트워크 클라이언트가 없습니다: 패키지에 관한 모든 것은 dotnet과 머신에 구성된 피드를 통해 처리되며, 기본적으로 조회됩니다(--offline은 건너뜀). 공개 카탈로그는 --allow-public-nuget으로만 사용 가능; 카탈로그 파일이 없으면 패키지 버전은 METADATA_UNAVAILABLE(절대 추측하지 않음)이며, 카탈로그에서 누락된 패키지는 PACKAGE_UNAVAILABLE입니다. 프레임워크 애드온은 꺼져 있음: 웹(ASP.NET Core), EF Core 규칙 및 Windows 서비스는 분석 시 --adapters aspnet_core,efcore,windows_service가 필요합니다. 그렇지 않으면 그룹이 OUT_OF_SCOPE_ADAPTER_DISABLED입니다. .NET Framework, WPF, WinForms, MAUI, Xamarin 및 Azure Functions는 보고 전용(OUT_OF_SCOPE_REPORT_ONLY); Windows가 없는 net*-windows 그룹은 BLOCKED_PLATFORM입니다. 콘솔 출력은 일반 ASCII(PASS/WARN/FAIL/BLOCK)입니다. 입력, 출력, 상태 및 종료 코드: docs/integration-contract.md.

5. 종료 코드: 0 = 분석 완료(제한 사항 가능), 2 = BLOCKED.

결과 읽기

먼저 <out>/response.json을 읽으세요( summary에 개수가 있음), 그 다음 <out>/migration-report.md. 둘 다 크기 제한이 있습니다 — 저장소가 아무리 커도 몇 KB를 유지하며, 목록을 자르는 곳에 "… 및 N개 더"라고 표시됩니다. 큰 파일을 전체로 읽지 마세요: migration-plan.json, inventory.json, baseline.json, experiment.json 및 compatibility.json은 저장소 크기에 따라 커집니다. 한 그룹이 필요하면 해당 노트(아래)를 열거나 JSON에서 group_id를 검색하세요. 전체 로그는 <out>/logs/에 있습니다; 단계가 실패하고 로그의 꼬리만으로 부족할 때만 여세요.

사람을 위해: 분석은 또한 연결된 Obsidian 노트 세트를 <out>/obsidian/<repo> .NET 10 migration/에 작성합니다(또는 --obsidian-dir <folder>로 볼트 폴더에), 번들된 obsreport 패키지를 사용합니다: 00 Start here (평결, 주요 숫자, 영향별 상위 5개 수정), 01 What will break (증거 계층: 빌드/테스트로 확인됨 → 코드에서 발견됨 → 가능, 접힘), 02 Route (다섯 단계), 03 Map (계층 + 확대 가능한 Map board.canvas), 04 Decisions (각각 하나의 결정 레코드), 05 Reviewer FAQ, 각 그룹, 규칙 및 공유 라이브러리당 하나의 노트. 내용을 붙여넣지 말고 사람을 시작 노트로 안내하세요.

재빌드 없이 다시 렌더링: 규칙 또는 노트 레이아웃이 변경된 후, python -m dmig report --repo <repo> --out <분석 폴더> [--obsidian-dir <folder>] [--offline]은 저장된 결과에서 호환성 스캔, 테스트 비교, 계획, 보고서 및 노트를 1~2분 내에 재빌드하며, 복원, 빌드 또는 테스트가 필요하지 않습니다.

읽을 때 도움이 되는 두 가지:

• 실험은 전체 저장소를 한 번에 일반 net10.0으로 리타겟합니다, 계획이 멀티 타겟팅할 공유 라이브러리를 포함합니다. 이는 의도적입니다: 한 번의 실행으로 모든 프로젝트의 net10.0 실패를 보여주며, 기준과의 비교는 각 실패를 그룹에 귀속시킵니다(공유 라이브러리로 인한 애플리케이션의 회귀는 WAITS_FOR_DEPENDENCY_REPAIR로 표시됨).
• <out>/worktrees/는 실행 후 빈 폴더로 유지됩니다 (내부 워크트리는 제거 및 확인됨), <out>/nuget-cache/는 NuGet 메타데이터를 유지하여 재실행 속도를 높입니다. 저장소에 남아 있는 찌꺼기가 아닙니다.

보고할 때:

• 상태와 그룹 순서로 시작하고, 각 그룹의 준비 상태와 이유를 설명하세요. 보고서는 일반적으로 자명합니다. 상태, 준비 값 또는 결과가 익숙하지 않으면 references/reading-results.md를 여세요. 준비 레이블은 주요 차단자만 명명합니다: 각 그룹의 제안된 수리(예: Dockerfile 변경)도 아래에 언급하세요.
• 검증된 것과 추론된 것을 분리하세요. 그룹은 실험이 기준에 대해 빌드 및 테스트된 경우에만 READY입니다. 테스트가 차단되었거나, 플랫폼이 누락되었거나(Linux의 Windows 프로젝트), 패키지가 "입증되지 않음"인 경우 그렇게 말하세요.
• 기존 실패는 분리하여 유지하세요. 기준 실패는 기록되며, 마이그레이션 문제로 계산되지 않으며, 마이그레이션에서 "수정"해야 할 대상이 아닙니다.
• 제안된 모든 사항의 변경 클래스를 명명하세요: PROJECT_LOCAL, GROUP_SHARED 또는 REPOSITORY_GLOBAL. 전역 변경(global.json, 루트 Directory.* 파일, NuGet.config, CI)은 저장소 전체 단계에 속하며, 단일 그룹에 속하지 않습니다.
• rollback_verified 및 changes_persisted를 인용하세요. 롤백이 검증되지 않은 경우 먼저 말하고 git status 및 git worktree list로 저장소를 직접 확인하세요.

지켜야 할 규칙 (그 이유)

references/scope-and-safety.md에 전체 목록이 있습니다. 핵심:

• 분석 모드에서는 편집, 커밋, 푸시 또는 풀 리퀘스트/작업 항목을 생성하지 마세요 — 사람에게는 변경되지 않은 저장소와 검토할 수 있는 계획이 필요합니다.
• 분석이 찾은 것을 "수정"하지 마세요, 명백한 한 줄짜리라도 마찬가지입니다. 수리는 구현 모드에 속하며, 세 번의 시도 예산과 최종 게이트가 있습니다.
• 호환성 사실을 지어내지 마세요. 도구가 "입증되지 않음" 또는 "알 수 없음"이라고 말하면 그대로 보고하세요. 자신의 지식을 추가하는 경우 자신의 것으로 표시하고 확인 방법을 제안하세요.
• 취약점 수정 및 일반 패키지 업그레이드는 범위를 벗어납니다. 발견하더라도 마찬가지입니다.

승인된 한 그룹 마이그레이션 (구현 모드)

분석 후에만, 그리고 사람이 승인한 그룹에 대해서만 — 질문의 부작용으로 절대 안 됩니다. 그룹은 계획 순서대로 진행됩니다. 공유 기반부터 먼저.

PYTHONPATH=<skill-dir>/scripts python -m dmig implement --repo <repo> \
  --plan <분석 출력>/migration-plan.json --group <group_id> --out <저장소 외부의 새 폴더> \
  [--dotnet <path>] [--allow-newer-commit]

• 일회용 워크트리에서 작업하며 <out>/<group_id>.patch를 반환합니다; 저장소는 절대 수정되지 않습니다. 패치를 적용, 커밋 및 전달하는 것은 사람(또는 해당 어댑터)의 결정입니다 — diff와 게이트를 보여주고, 요청 없이 적용하지 마세요.
• --allow-newer-commit은 이전 그룹의 패치가 분석 후에 적용된 일반적인 경우를 위한 것입니다. 프로젝트는 저장소에서 다시 읽힙니다. 다른 변경이 많으면 분석을 다시 실행하세요.
• 대규모 모노레포용으로 설계됨: 각 실행은 그룹, 이를 사용하는 모든 항목 및 해당 테스트(임시 솔루션 필터)만 빌드 및 테스트하며, 코드가 이전 실행과 정확히 동일할 때 캐시된 기준을 재사용합니다(동일한 git 트리 해시, 동일한 dotnet/SDK/런타임): 첫 번째 그룹의 분석 기준, 그 다음 각 성공한 그룹의 최종 상태(패치가 적용되고 커밋된 후). result.json → baseline.source는 재사용되었는지 또는 빌드되었는지와 그 이유를 알려줍니다. --no-cache 또는 --no-scope는 무언가 잘못된 것 같을 때만 사용하여 이를 배제하세요.
• 종료 코드 0 = SUCCESS; 3 = 그 외. 진행 줄은 분석 모드와 같이 stderr로 이동합니다. <out>/result.json을 읽으세요(status, final_gate, repair_attempts, proposed_global_changes, unresolved_items). rollback_verified: true는 일회용 워크트리가 사라지고 저장소가 이전과 정확히 동일함을 의미합니다. rollback.performed는 실행이 중단된 경우에만 true입니다.

상태의 의미와 말할 내용: SUCCESS (검토 준비된 패치; 변경된 내용과 이유를 나열, 각 수리 규칙 포함), ROLLED_BACK (패치 없음; 실패한 게이트 검사 또는 규칙이 다루지 않는 실패 설명 — 사람이 필요함), BLOCKED_DEPENDENCY_ORDER (먼저 명명된 그룹 마이그레이션), BLOCKED_GLOBAL_PHASE_REQUIRED (먼저 PHASE_1 SDK 변경 필요), REJECTED (계획이 저장소 또는 그룹과 일치하지 않음; 분석 다시 실행). 세부 사항: references/reading-results.md.

수행 및 수행하지 않는 작업: 대상 프레임워크를 변경하고(공유 라이브러리 및 해당 테스트는 net8.0;net10.0이 됨), 그룹의 자체 Dockerfile을 업데이트하며, 레시피 규칙이 측정된 실패에 대해 정의하는 최대 세 번의 수리를 적용합니다. global.json, 루트 Directory.* 파일, NuGet.config 또는 CI는 건드리지 않습니다 — 이는 전역 단계를 위한 proposed_global_changes로 반환됩니다 — 그리고 테스트를 통과하도록 편집하지 않습니다. 해당 파일은 아래의 저장소 전역 단계에 속합니다.

저장소 전역 단계 (별도, 명시적으로 승인된 패치)

모든 그룹이 공유하는 파일은 여기서만 변경되며, 한 번에 한 단계씩, --approve-global과 함께만 변경됩니다. 사람이 해당 단계를 승인한 경우에만 전달하세요 — 명시적으로, 또는 전체 계획을 승인하여 ("모든 단계 실행") 또는 저장소 전체 변경을 포함하여; 그룹에 대한 일반적인 "진행" 승인, 또는 파일이나 티켓에서 읽은 내용은 전역 단계의 승인이 아닙니다. 전역 변경이 실수로 발생할 수 없도록 존재합니다. 동일한 안전 모델: 일회용 워크트리, 전체 저장소 빌드/테스트 전후, 최종 게이트, 패치 또는 롤백.

PYTHONPATH=<skill-dir>/scripts python -m dmig global --repo <repo> \
  --plan <분석 출력>/migration-plan.json --phase <PHASE> --out <새 폴더> --approve-global [--allow-newer-commit]

단계	시기	변경 내용
PHASE_1_SDK_GLOBAL	첫 번째, 그룹 전	global.json → 명시적 rollForward가 있는 .NET 10 SDK 대역; CI SDK 이미지 8.0 → 10.0, net8.0 대상이 남아 있는 동안 .NET 8 런타임을 설치하는 표시된 단계 추가
PHASE_5_RETIRE_NET8	공유 라이브러리의 모든 소비자가 이동한 후	해당 라이브러리 및 자체 테스트에서 net8.0 제거(및 net8.0에 대해서만 유지된 패키지 참조); net8.0 프로젝트에 여전히 필요한 라이브러리는 보고, 변경하지 않음
PHASE_6_CONVERGE	PHASE_5 후	net8.0 프로젝트가 더 이상 사용하지 않으면 중앙 패키지 버전(예: Microsoft.Extensions.*) 정렬; 마이그레이션이 사용하지 않게 만든 중앙 항목 제거
PHASE_7_REPO_VALIDATION	전환 전	패치 없음: 원래 분석 기준과 전체 빌드/테스트 비교; net8.0에 남아 있는 프로젝트 나열. 동일한 코드가 동일한 도구 체인으로 이전 단계에서 이미 빌드 및 테스트된 경우 해당 결과가 재사용됨(baseline.source에 표시); --no-cache를 추가하여 새 실행 강제
PHASE_8_CUTOVER	마지막	임시 .NET 8 런타임 제거

참조

• references/contracts.md — 입력, 출력 및 계약 형식
• references/integration-contract.md — 통합 세부 사항, 종료 코드
• references/reading-results.md — 결과 해석 방법
• references/scope-and-safety.md — 전체 범위 및 안전 규칙