쉘 스크립트 기준 및 스타일 가이드

GitLab은 다양한 서비스 및 하위 프로젝트로 구성됩니다. 그들의 대다수 백엔드 코드는 Ruby 및 Go로 작성되었습니다. 그러나 일부는 배포, 설치 등과 같은 루틴 시스템 관리 작업을 자동화하기 위해 셸 스크립트를 사용합니다. 이는 역사적인 이유로 또는 도커 이미지를 위해 종속성을 최소화하기 위한 노력의 결과입니다.

이 페이지는 우리의 다양한 경험을 기반으로 셸 스크립트 가이드라인을 정의하고 조직화하는 것을 목표로 합니다. GitLab 프로젝트 전반에 걸쳐 있는 모든 셸 스크립트는 이 가이드와 최종적으로 조화를 이루어야 합니다. 이 가이드에서 벗어나는 프로젝트별 이탈이 있다면 해당 프로젝트의 README.md 또는 PROCESS.md 파일에 설명해야 합니다.

셸 스크립트 사용을 피하십시오

경고: 반드시 읽어야 할 섹션입니다.

앞서 말했듯, 가능한 한 셸 스크립트 사용을 피하는 것을 권장합니다. Ruby나 Python과 같은 고수준 해석 언어가 거의 항상 더 나은 선택입니다(우리가 활용하는 코드베이스와 일관성을 유지하기 위해 필요한 경우). 고수준 해석 언어는 더 가독성이 좋고 단위 테스트, 린팅 및 오류 보고에 대해 훨씬 더 성숙한 기능을 제공합니다.

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

이 가이드의 범위

GitLab 설치 요구 사항에 따르면, 이 가이드는 지원되는 리눅스 배포판에서 사용된 셸에만 적용됩니다.

셸 언어 선택

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

코드 스타일 및 형식

이 섹션에서는 프로젝트에 셸 스크립트가 포함되어 있다면 필수적으로 프로젝트의 CI/CD 파이프라인의 일부로 되어야 하는 도구를 설명합니다. 이러한 도구는 셸 코드 서식 지정, 오류 또는 취약점 확인 등을 자동화합니다.

린팅

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

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

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

참고: 기본적으로 ShellCheck는 셸 감지를 사용하여 사용 중인 셸 방언을 결정합니다. 셸 파일이 제어 범위를 벗어나고 ShellCheck가 방언을 감지하지 못하는 경우 -s 플래그를 사용하여 방언을 지정하세요: -s sh 또는 -s bash.

형식 지정

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

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

Linting 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는 셸 감지를 사용하며 마침표로 시작하는 파일을 무시합니다. 이를 재정의하려면 -ln 플래그를 사용하여 셸 방언을 지정하세요: -ln posix 또는 -ln bash.

테스트

참고: 작업 중입니다.

셸 스크립트의 자동 테스트에 대한 평가를 위해 (예: BATS) 등과 같은 다양한 도구를 평가하는 지속적인 노력이 이루어지고 있습니다.

코드 리뷰

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

그러나 권장되는 조치는 상기 도구를 사용하고 보고된 위반 사항을 해결하는 것입니다. 이를 통해 코드 리뷰가 필요하지 않게 될 것입니다.

Development documentation으로 돌아가기.