@types/node 버전 어디에 맞춰야 함?

node 버전 업데이트 하다가 문득 궁금해져서 쓰게 되었습니다.
핵심 내용은 How do Definitely Typed package versions relate to versions of the corresponding library? 에 있고, 그 내용을 번역해보았습니다.

NOTE: The discussion in this section assumes familiarity with Semantic versioning

이 섹션의 내용은 [시맨틱 버저닝(Semantic Versioning)]에 대한 이해를 전제로 합니다.

Each Definitely Typed package is versioned when published to npm. The DefinitelyTyped-tools (the tool that publishes @types packages to npm) will set the declaration package's version by using the major.minor.9999 version number listed in package.json.

각 Definitely Typed 패키지는 npm에 배포될 때 버전이 지정됩니다.
DefinitelyTyped-tools(npm에 @types 패키지를 배포하는 도구)는
package.json에 있는 major.minor.9999 형식의 버전을 사용해 타입 선언 패키지의 버전을 설정합니다.

For example, here are the first few lines of Node's type declarations for version 20.8.x at the time of writing:

예를 들어, 작성 시점에 Node 20.8.x 버전의 타입 선언 패키지 첫 부분은 다음과 같습니다:

{
    "private": true,
    "name": "@types/node",
    "version": "20.8.9999"
}

Because the version is listed as 20.8.9999, the npm version of the @types/node package will also be 20.8.x.

버전이 20.8.9999로 되어 있기 때문에, npm에서 배포되는 @types/node 패키지의 버전도 20.8.x가 됩니다.

Note that the version in package.json should only contain major.minor version (e.g. 10.12) followed by .9999. This is because only the major and minor release numbers are aligned between library packages and type declaration packages.

package.json의 버전은 major.minor 버전(예: 10.12) 뒤에 .9999가 붙은 형태여야 합니다.
이유는 라이브러리 패키지와 타입 선언 패키지는 major와 minor 버전만 맞추기 때문입니다.

(The .9999 is to ensure that local @types packages are always newest during local development.)

(.9999는 로컬 개발 시 @types 패키지가 항상 최신으로 인식되도록 하기 위해 붙습니다.)

The patch release number of the type declaration package (e.g. .0 in 20.8.0) is initialized to zero by Definitely Typed and is incremented each time a new @types/node package is published to npm for the same major/minor version of the corresponding library.

타입 선언 패키지의 패치(patch) 번호(예: 20.8.0에서 .0)는
Definitely Typed에서 0으로 시작하며, 같은 major/minor 버전의 라이브러리에 대해 새로운 @types/node 패키지가 npm에 배포될 때마다 1씩 증가합니다.

Sometimes type declaration package versions and library package versions can get out of sync. Below are a few common reasons why, in order of how much they inconvenience users of a library. Only the last case is typically problematic.

때때로 타입 선언 패키지 버전과 라이브러리 버전이 맞지 않을 수 있습니다.
아래는 그 이유를, 사용자 불편이 적은 순서대로 나열한 것입니다. (마지막 경우만이 보통 문제를 일으킵니다.)

As noted above, the patch version of the type declaration package is unrelated to the library patch version. This allows Definitely Typed to safely update type declarations for the same major/minor version of a library.

앞서 설명했듯, 타입 선언 패키지의 패치 버전은 라이브러리의 패치 버전과 무관합니다.
이 덕분에 같은 major/minor 버전 범위 안에서 타입 선언을 안전하게 업데이트할 수 있습니다.

If updating a package for new functionality, don't forget to update the version number to line up with that version of the library. If users make sure versions correspond between JavaScript packages and their respective @types packages, then npm update should typically just work.

새로운 기능을 위해 패키지를 업데이트할 경우, 해당 라이브러리 버전에 맞게 버전 번호를 업데이트해야 합니다.
JavaScript 패키지와 그에 해당하는 @types 패키지의 버전을 맞춰두면, 일반적으로 npm update가 문제없이 동작합니다.

It's common for type declaration package updates to lag behind library updates because it's often library users, not maintainers, who update Definitely Typed when new library features are released. So, there may be a lag of days, weeks or even months before a helpful community member sends a PR to update the type declaration package for a new library release. If you're impacted by this, you can be the change you want to see in the world and you can be that helpful community member!

새로운 라이브러리 기능이 나왔을 때, 타입 선언 패키지 업데이트가 라이브러리보다 늦어지는 경우가 많습니다.
이는 대부분의 경우 라이브러리 유지보수자가 아닌 라이브러리 사용자가 Definitely Typed를 업데이트하기 때문입니다.
그래서 새로운 라이브러리가 릴리스된 후, 커뮤니티의 누군가가 PR을 보내 타입 선언을 업데이트하기까지 며칠, 몇 주, 심하면 몇 달이 걸릴 수 있습니다.
만약 이런 지연이 불편하다면, 직접 기여자가 되어 PR을 보낼 수도 있습니다.

❗ If you're updating type declarations for a library, always set the major.minor version in package.json to match the library version that you're documenting! ❗

❗ 라이브러리 타입 선언을 업데이트할 때는, package.json의 major.minor 버전을 반드시 해당 라이브러리 버전과 일치시켜야 합니다! ❗

📌 Definitely Typed 패키지 버전 ↔ 라이브러리 버전 관계 요약

1. 버전 규칙

   • @types 패키지는 major.minor.9999 형식으로 package.json에 기록됨
   • .9999는 로컬 개발 시 항상 최신으로 인식되도록 설정
   • npm 배포 시 major/minor만 라이브러리 버전과 맞춤

2. 패치 버전 관리

   • 타입 선언 패키지의 패치 번호(.0, .1 등)는 라이브러리 패치 버전과 무관
   • 같은 major/minor 버전 내에서 새로운 타입 선언이 나오면 패치 번호를 1씩 증가

3. 버전 불일치 원인

   • 패치 버전은 원래부터 다를 수 있음(문제 없음)
   • 기능 업데이트 시 major/minor 버전을 라이브러리와 맞추지 않은 경우
   • 커뮤니티 기여 지연으로 타입 선언 업데이트가 늦어지는 경우(며칠~몇 달)

4. 권장 사항

   • 새로운 기능에 맞춰 타입 선언을 업데이트할 때는 반드시 major.minor 버전을 라이브러리와 동일하게 설정
   • 라이브러리와 @types 버전이 맞으면 npm update가 정상적으로 동작

---

"내가 쓰는 메이저, 마이너 버전은 일치시킨 뒤 패치 버전은 가장 최신을 맞추면 되겠다."