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 index를 참고하십시오.)

  이 글을 쓰는 시점 기준, 다음 도구가 “nightly 전용“입니다: embedded-book.

toolstate 저장소 업데이트하기

toolstate 저장소 업데이트는 두 단계로 이루어집니다. CI가 auto 브랜치(bors가 PR을 통합에 적합한지 테스트하기 위해 옮기는 곳)에서 실행될 때, 개별 플랫폼(이 글을 쓰는 시점 기준 Linux와 Windows)의 “tool” 러너들이 각각 테스트 중인 커밋에 대한 각 도구의 상태를 기록한 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. 서브모듈과 필요한 빌드 시스템/부트스트랩 업데이트를 함께 추가하는 PR을 rust-lang/rust에 생성하십시오. 이와 같은 문제를 피하기 위해 테스트가 ./x.py --no-fail-fast를 제대로 지원하는지 주의 깊게 확인하십시오.
2. checktools.sh에 대한 변경 사항을 포함합니다:
   • 최상단에서 도구를 빌드합니다. 이 단계에서 도구에 대한 JSON 상태를 실제로 생성합니다. config.toml에서 save-toolstates가 설정되면, rust 빌드 시스템이 각 테스트의 상태를 담은 JSON 파일을 작성합니다.
   • 해당 도구가 beta 블로커여야 하는지 여부와 함께 status_check에 도구를 추가하십시오.
3. publish_toolstate.py를 업데이트하여 도구를 추가합니다. 여기에는 도구가 깨졌을 때 핑할 사람들의 목록과 소스 저장소가 포함됩니다. (참고: 이 글을 쓰는 시점 기준, 이 사용자들은 rust-lang/rust GitHub에서 지정 가능한 권한을 가지고 있어야 합니다.)
4. toolstate 저장소에 latest.json 파일에 도구를 수동으로 추가하는 PR을 제출하십시오.