셸 스크립트 표준 및 스타일 가이드라인

GitLab은 여러 가지 서비스와 하위 프로젝트로 구성되어 있습니다. 대부분의 백엔드 코드는 Ruby 및 Go로 작성되어 있습니다. 그러나 일부 프로젝트는 배포, 설치 등과 같은 일상적인 시스템 관리 작업의 자동화를 위해 셸 스크립트를 사용합니다. 이는 역사적인 이유로 또는 Docker 이미지와 같은 종속성을 최소화하기 위한 노력으로 이루어집니다.

이 페이지는 우리의 다양한 경험을 기반으로 우리의 셸 스크립트 가이드라인을 정의하고 조직하는 것을 목표로 합니다. GitLab 프로젝트의 모든 셸 스크립트는 궁극적으로 이 가이드에 harmonized되어야 합니다. 이 가이드의 프로젝트별 편차가 있다면 해당 프로젝트의 README.md 또는 PROCESS.md 파일에 설명되어야 합니다.

셸 스크립트 사용 피하기

경고:
이 섹션은 꼭 읽어야 합니다.

위의 모든 내용을 감안할 때, 가능한 한 셸 스크립트를 피하는 것이 좋습니다. Ruby나 Python과 같은 언어(우리가 활용하는 코드베이스와의 일관성을 위해 필요할 경우)는 거의 항상 더 나은 선택입니다.

고급 인터프리터 언어는 더 가독성이 높은 문법을 제공하며, 단위 테스트, 린팅 및 오류 보고에 대한 더 성숙한 기능을 제공합니다.

프로젝트의 종속성 크기에 대한 강한 제한이나 특정 사례에서 더 중요한 다른 요구 사항이 있을 경우에만 셸 스크립트를 사용하십시오.

이 가이드의 범위

GitLab 설치 요구 사항에 따르면, 이 가이드는 supported Linux distributions에서 사용하는 셸만 다룹니다.

즉,

셸 언어 선택

  • 종속성 목록을 줄여야 할 때는 환경에서 제공되는 것을 사용하십시오. 예를 들어, Docker 이미지의 경우 대부분의 도구 이미지의 기본 이미지인 alpine의 sh를 사용합니다.
  • 그 외의 경우에는 가능하다면 bash를 사용하십시오. bash는 sh보다 더 강력하지만 여전히 널리 사용되는 셸입니다.

코드 스타일 및 형식

이 섹션에서는 셸 스크립트를 포함하는 프로젝트의 CI 파이프라인에서 필수적으로 사용해야 할 도구를 설명합니다. 이러한 도구들은 셸 코드 형식을 자동화하고 오류나 취약성을 검사하는 등의 역할을 합니다.

린팅

우리는 기본 구성에서 셸 스크립트를 린트하기 위해 ShellCheck 유틸리티를 사용합니다.

셸 스크립트가 있는 모든 프로젝트는 다음과 같은 GitLab CI/CD 작업을 사용해야 합니다:

shell check:
  image: koalaman/shellcheck-alpine:stable
  stage: test
  before_script:
    - shellcheck --version
  script:
    - shellcheck scripts/**/*.sh  # 셸 스크립스의 경로

주목:
기본적으로, ShellCheck는 사용 중인 셸 방언을 결정하기 위해 shell detection을 사용합니다. 셸 파일이 사용자의 제어 범위를 벗어나고 ShellCheck가 방언을 감지할 수 없는 경우, -s 플래그를 사용하여 지정하십시오: -s sh 또는 -s bash.

형식

일관된 형식을 유지하기 위해 shfmt 도구를 사용하는 것이 좋습니다. 우리는 Google Shell Style Guide에 따라 셸 스크립트를 형식화하므로 다음 shfmt 호출을 프로젝트의 스크립트 파일에 적용해야 합니다:

shfmt -i 2 -ci -w scripts/**/*.sh

린팅 GitLab CI/CD 작업과 더불어, 셸 스크립트가 있는 모든 프로젝트는 다음 작업도 사용해야 합니다:

shfmt:
  image: mvdan/shfmt:v3.2.0-alpine
  stage: test
  before_script:
    - shfmt -version
  script:
    - shfmt -i 2 -ci -d scripts  # 셸 스크립스의 경로

주목:
기본적으로, shfmt는 ShellCheck와 유사한 shell detection을 사용하며, 점으로 시작하는 파일을 무시합니다. 이를 재정의하려면 -ln 플래그를 사용하여 셸 방언을 지정하십시오: -ln posix 또는 -ln bash.

테스트

참고:

이것은 진행 중인 작업입니다.

쉘 스크립트의 자동 테스트를 위해 다양한 도구를 평가하는 진행 중인 노력입니다(예: BATS).

코드 리뷰

코드 리뷰는 다음에 따라 수행되어야 합니다:

그러나 권장되는 조치는 앞서 언급한 도구를 사용하고 보고된 위반 사항을 해결하는 것입니다.

이것은 코드 리뷰의 필요성을 제거해야 합니다.

개발 문서로 돌아가기.