rustc 저장소에 포함된 도구 처리(“toolstate”)

Rust 저장소에는 여러 외부 git 서브모듈(예: Book, Reference)이 포함되어 있습니다. toolstate 시스템은 beta 릴리스를 제외하고 이러한 서브모듈이 깨진 상태로 있는 것을 허용하기 위해 사용됩니다.

이는 문서가 rust-lang/rust CI와 문서 저장소의 CI 양쪽에서 모두 테스트되기 때문에 필요합니다. rustc에 문서를 깨뜨리는 변경이 있으면, 문서를 깨뜨리는 그 rustc 버전은 아직 병합되지 않아 존재하지 않으므로 문서를 업데이트할 수 없습니다. 일반적으로 두 저장소 모두에서 CI가 통과 상태여야 합니다.

toolstate 시스템은 rust-lang/rust에서 문서가 일시적으로 “실패” 상태에 있는 것을 허용함으로써 이 문제를 해결합니다. 테스트가 실패하기 시작하면 해당 서브모듈의 메인테이너에게 알림이 전송됩니다. 그러면 메인테이너가 이를 수정할 책임을 집니다.

“도구“가 가질 수 있는 세 가지 상태는 test-pass, test-fail, build-fail입니다.

이 페이지에서는 toolstate 시스템이 어떻게 동작하는지, 그리고 어떤 도구가 언제 깨지는 것이 허용되는지(또는 허용되지 않는지)에 대한 규칙을 개략적으로 설명합니다.

참고: 과거에는 toolstate 시스템이 컴파일러와 밀접하게 결합된 도구(rustfmt나 miri 등)를 관리하는 데 사용되었습니다. 그러나 이후 이러한 도구는 git 서브트리를 사용하도록 전환되었으므로, 해당 도구는 항상 테스트를 통과해야 하며 모든 실패는 이를 깨뜨린 PR 안에서 해결되어야 합니다.

이 문서는 “도구“라는 용어를 사용하지만, 이 글을 쓰는 시점에서 추적되는 대상은 외부 문서뿐입니다.

Toolstate 규칙

• 모든 도구에 대해, PR이 해당 도구를 변경하는 경우(서브모듈이 사용하는 커밋을 변경하는 경우) 해당 PR 이후 도구는 test-pass 상태여야 하며, 그렇지 않으면 CI가 실패합니다.

• “nightly 전용” 도구를 제외한 모든 도구에는 다음과 같은 추가 규칙이 적용됩니다.

  • PR이 beta 또는 stable 브랜치에 병합되는 경우, 도구는 test-pass 상태여야 합니다.
  • beta가 만들어지기 전 주에 PR이 기본 브랜치에 병합되고 해당 PR이 도구를 회귀시키는 경우(상태를 “악화“시키는 경우), CI가 실패합니다. 이는 beta를 만들 수 있도록 모든 도구가 test-pass 상태가 되도록 돕기 위한 것입니다. (다음 beta 컷오프가 언제인지는 Forge 색인을 참고하십시오.)

  이 글을 쓰는 시점에서 “nightly 전용” 도구는 embedded-book입니다.

toolstate 저장소 업데이트

toolstate 저장소의 업데이트는 두 단계로 이루어집니다. CI가 auto 브랜치(bors가 PR을 통합해도 좋은지 테스트하기 위해 옮기는 곳)에서 실행될 때, 개별 플랫폼(이 글을 쓰는 시점에서는 Linux와 Windows)의 “도구” 러너가 각각 테스트 중인 커밋에 대한 각 도구의 상태를 기록한 JSON 파일을 저장소에 제출합니다. 이후 해당 커밋이 실제로 CI를 완전히 통과하고 bors가 이를 기본 브랜치로 옮기면, toolstate 저장소의 “현재 도구 상태“가 적절히 업데이트됩니다.

또한 이 스크립트들은 도구가 깨지면 자동으로 일부 사람들에게 핑을 보내고 이슈를 생성합니다.

자세한 내용은 관련 파일인 checktools.sh, publish_toolstate.py 및 그 안에서 언급된 다른 파일의 주석을 참고하십시오.

도구 업데이트

서브모듈을 적절한 커밋으로 업데이트하여 도구를 업데이트할 수 있습니다.

git submodule update --remote path/to/submodule을 실행하고, 업데이트 내용을 추가한 뒤, 테스트가 통과하는지 확인하고, 커밋한 다음 풀 리퀘스트를 보내십시오. 경로는 rust 저장소의 루트를 기준으로 하므로, 예를 들어 reference의 경로는 src/doc/reference입니다.

필수는 아니지만 subup이 이 작업에 도움이 될 수 있습니다.

도구 추가

참고: 저희는 점진적으로 서브모듈과 toolstate에서 벗어나려 하고 있습니다. 서브모듈 대신 서브트리를 추가하는 것을 고려하십시오: #70651

추적할 새 도구를 추가하려면 다음 단계를 거쳐야 합니다:

1. 서브모듈과 함께 필요한 빌드 시스템 / bootstrap 변경 사항을 추가하는 PR을 rust-lang/rust에 생성하십시오. 이와 같은 이슈를 피하려면 테스트가 ./x.py --no-fail-fast를 제대로 지원하는지 주의하십시오.
2. checktools.sh에 대한 변경 사항을 포함하십시오:
   • 맨 위에서 도구를 빌드하십시오. 이 단계가 실제로 도구의 JSON 상태를 생성하는 단계입니다. config.toml에 save-toolstates가 설정되어 있으면 Rust 빌드 시스템이 각 테스트의 상태를 담은 JSON 파일을 작성합니다.
   • 도구를 status_check에 추가하고, beta 블로커로 지정할지 여부도 함께 지정하십시오.
3. publish_toolstate.py를 수정하여 도구를 추가하십시오. 여기에는 도구가 망가졌을 때 핑할 사람 목록과 도구의 소스 저장소가 포함됩니다. (참고: 이 글을 작성하는 시점 기준으로, 이 사용자들은 rust-lang/rust GitHub에서 담당자로 지정될 수 있는 권한을 가지고 있어야 합니다.)
4. toolstate 저장소에 PR을 제출하여 latest.json 파일에 도구를 수동으로 추가하십시오.