다른 코드가 확장해 쓰는 공개 서버 패키지를 깨뜨리지 않고 변경하기

## 공개 배포되는 내용을 확인하고 비밀 정보 빼기 편집하기 전에 패키지의 배포 대상, 라이선스, 모듈 시스템, 언어, 런타임 역할 및 동기화 경로를 파악하십시오. 비공개 워크스페이스에서 개발하더라도 공개적으로 동기화되는 패키지 안의 모든 파일을 공개 릴리스 콘텐츠로 취급하십시오. - 비밀 정보, 라이선스로 제한되는 동작 또는 내부 전용 픽스처를 공개 패키지 안에 절대 넣지 마십시오. - 서버 전용 패키지는 헤드리스 상태로 유지하고 브라우저나 DOM 종속성을 도입하지 마십시오. - 인접한 패키지의 패턴을 가져오지 말고 해당 패키지의 실제 모듈 및 언어 규칙을 따르십시오. - 워크스페이스에서 직접 의존하는 대상을 기록하고 외부에도 패키지 소비자가 더 있다고 가정하십시오. 워크스페이스 안에서 보이는 의존 대상이 하나뿐이더라도 공개 배포는 영향 범위를 확대합니다. ## 옛 콜백 방식과 깊은 경로 import가 계속 동작하게 하기 콜백을 promise나 async 함수로 소리 없이 현대화하지 마십시오. 여러 시대의 코드가 섞인 환경에서는 주변 호출부가 동기식이거나 promise 기반이더라도 확장 훅이 콜백 형태에 의존할 수 있습니다. 호출 방식을 변경하기 전에 다음을 수행하십시오. 1. 확장 지점의 모든 구현을 열거하십시오. 2. 인수 순서, 반환 동작, 콜백 시점 및 오류 의미 체계를 비교하십시오. 3. 변경하는 파일의 스타일을 따르십시오. 4. 지원되는 각 호출 형태에 대한 테스트를 추가하거나 업데이트하십시오. 다운스트림 저장소에서 딥 import를 검색하기 전에는 내부용처럼 보이는 유틸리티, 미들웨어 또는 모델 파일의 이름이나 위치를 변경하지 마십시오. 소스 경로 import는 암묵적인 공개 API이며 컴파일러 경고 없이도 깨질 수 있습니다. ## 미들웨어 순서와 훅 이름을 정확히 지키기 미들웨어 간 종속성을 명시적으로 보존하십시오. 권한 검사가 채워진 사용자 컨텍스트를 읽는 경우 인증 또는 토큰 해석이 권한 검사보다 먼저 실행되어야 합니다. 순서 변경을 서식 정리가 아닌 계약 변경으로 취급하십시오. 새 미들웨어를 만들 때는 요청 핸들러를 반환하는 패키지 인식 팩터리와 같이 패키지에 확립된 팩터리 형태를 복사하고, 중앙 체인의 의도한 지점에 등록하십시오. 기존 변경 훅 메커니즘을 확장 표면으로 사용하십시오. 호출 지점을 추가하기 전에 현재의 모든 훅 이름과 구현을 검색하십시오. 정확한 이름, 입력값, 콜백 또는 반환 형태 및 기본 동작을 확인하십시오. 훅 이름의 오타는 소리 없이 기본값을 반환할 수 있습니다. 다운스트림 구현자가 찾을 수 있는 위치에 새로운 확장 지점을 모두 문서화하십시오. ## 배포된 마이그레이션은 고치지 않고 새로 추가하기 병렬 패턴을 새로 만들지 말고 확립된 기본 추상화를 따르십시오. 새 데이터 모델은 공유 모델 플러그인이나 기본 형태를 사용해야 합니다. 새 최상위 REST 리소스는 공통 리소스 기반을 확장하고 중앙 진입점을 통해 경로를 등록해야 합니다. 배포된 데이터베이스 마이그레이션을 변경 불가능한 단방향 작업으로 취급하십시오. - 릴리스 후에는 기존 마이그레이션을 절대 편집하지 마십시오. - 이후의 모든 수정에는 번호가 부여된 새 마이그레이션을 추가하십시오. - 각 마이그레이션을 멱등하게 만드십시오. - 실행 중단과 시작 시 반복 실행을 고려하십시오. - 새 데이터베이스와 이미 마이그레이션된 데이터베이스 모두에서 동작을 검증하십시오. 다운스트림 패키지가 훅을 통해 모델 필드나 동작을 주입하는 경우 스키마, 기본값, 직렬화 또는 하이드레이션을 변경하기 전에 해당 주입 지점을 점검하십시오. ## 변경이 영향을 주는 다른 패키지를 찾아 양쪽 테스트하기 구현하기 전에 변경 사항과 그 소비자의 대응 관계를 파악하십시오. 인증 미들웨어, 권한 처리, 세션 경계, 공유 유틸리티, 암호화 도우미, 모델 훅 또는 확장 지점 시그니처를 변경할 때는 다운스트림 호출자와 조율하십시오. 깊은 경로로 import되는 도우미를 공개 API로 취급하십시오. 토큰 소유권과 세션 소유권의 구분을 아키텍처 경계로 취급하십시오. 값을 참조로 저장하고 읽을 때 하이드레이션하는 경우 표현 방식을 변경하기 전에 기록 측과 역참조 처리기를 모두 점검하십시오. 여러 영역에 걸친 모든 편집에 대해 다음을 수행하십시오. 1. 관련 아키텍처, 종속성 및 알려진 주의 사항 문서를 읽으십시오. 2. 다운스트림 구현과 호출 지점을 검색하십시오. 3. 반드시 유지되어야 하는 계약을 명시하십시오. 4. 경계 양쪽을 모두 테스트하십시오. 5. 의도적인 계약 변경과 그 마이그레이션 경로를 문서화하십시오. ## 가상 머신 경계를 넘는 값 테스트하기 가상 머신 번들, shim, 평가기 인스턴스, 리소스 한도 또는 오류 의미 체계를 변경하려면 전체 클라이언트-서버 계약을 점검해야 합니다. 호스트와 샌드박스 shim을 동등하게 유지하고 번들을 다시 빌드한 뒤, 값이 런타임 경계를 통과해도 보존되는지 검증하십시오. 격리된 런타임을 통해 직렬화된 활성 데이터베이스 객체가 동일성이나 프로토타입을 유지한다고 가정하지 마십시오. 식별자, 참조, 날짜, 버퍼, 오류 및 하이드레이션된 값을 양방향으로 테스트하십시오. 모듈 로드 시 초기화되는 호환성 shim이 프로세스 전체의 호스트 상태를 변경할 수 있다는 점에 주의하십시오. 패키지를 헤드리스로 유지하려는 경우에도 가짜 브라우저 컨텍스트가 전역 상태를 만들 수 있습니다. 커버리지에서 제외된 번들 코드를 알려진 테스트 공백으로 취급하고, 일반적인 커버리지가 이를 입증한다고 가정하지 말고 표적 실행 검사를 추가하십시오. ## 시작할 때 데이터베이스 기능을 확인하고 대체 경로 두기 시작 시 지원 기능을 탐지하여 여러 데이터베이스 구현을 지원하십시오. 고급 콜레이션, 조회 파이프라인, 복합 중첩 경로 인덱스 및 기타 기준선 이상의 기능은 탐지 결과에 따라 게이트하고 테스트된 대체 경로를 제공하십시오. 런타임이 지원 기능 맵을 제공하는 경우 제품 이름이나 버전 문자열로 호환성을 추론하지 마십시오. 반복적으로 되돌려진 변경은 탐지 및 대체 경로가 계약의 일부라는 증거입니다. 공개 패키지의 동작이 기능 플래그에 의존하지만 패키지에서 비공개 레지스트리를 import할 수 없다면 플래그의 정확한 키 문자열로 기존 확장 훅을 호출하십시오. 레지스트리에서 키를 확인하고 활성화 및 비활성화 경로를 모두 테스트하십시오. 비공개 레지스트리 로직을 공개 패키지에 내장하지 마십시오. ## 패키지에 실제로 있는 테스트, 린트, 빌드 실행하기 패키지가 실제로 제공하는 스크립트를 기준으로 ‘통과’ 상태를 정의하십시오. JavaScript 전용 패키지에서는 존재하지 않는 타입 검사 단계를 만들어 내지 않고 전체 테스트 모음과 린터를 실행하는 것을 뜻할 수 있습니다. 변경 사항이 번들된 런타임 출력에 영향을 주면 빌드를 실행하십시오. 테스트가 자동 검색되지 않는다면 새 테스트 파일을 테스트 모음의 중앙 importer에 모두 등록하십시오. 등록되지 않은 테스트 파일은 아무런 보호도 제공하지 않습니다. 지원되는 테스트 이름 필터를 사용해 조사 범위를 좁히되 완료 전에는 필요한 전체 테스트 모음을 실행하십시오. 자동 수정 린트 명령은 신중하게 사용하고 그 diff를 검토하십시오. 테스트, 린트 및 관련 번들 빌드가 통과하는지 확인하고 런타임이나 호환성 문제를 드러내는 경고는 보존하십시오. ## 완료라고 하기 전에 영향 범위 전체 확인하기 가장 가까운 파일이 아니라 영향을 받는 계약에서 시작하십시오. 알려진 주의 사항과 다운스트림 종속성을 검색하고, 호환되는 최소 변경을 수행하며, 완료를 보고하기 전에 공개 릴리스의 안전성을 검증하십시오. 최종 검토에서 다음을 확인해야 합니다. - 비밀 정보, 사용이 제한된 자료 또는 내부 전용 자료가 공개 패키지에 들어가지 않았습니다. - 콜백, 훅, 딥 import 및 미들웨어 순서 계약이 여전히 유지됩니다. - 마이그레이션이 추가 방식이며 멱등합니다. - 영향을 받는 경우 모델, 참조, VM 및 데이터베이스 지원 기능 경계를 테스트했습니다. - 새 테스트를 등록했고 패키지의 실제 품질 게이트가 통과합니다. - 필요한 곳에서 패키지 간 호출자와 문서를 업데이트했습니다. - 호환성을 깨뜨리거나 메이저 릴리스를 요구하는 변경을 모든 배포 대상과 조율했습니다. 워크스페이스 종속성 수가 적다는 이유만으로 변경 사항을 격리된 것으로 판단하지 마십시오. 공개 소비자도 위험 모델의 일부입니다.