Orbit에서 프로젝트 README 보기

Docs 탭은 저장소의 README를 KPanel 내에 렌더링하므로, 프로젝트의 문서를 브라우저 탭에서 찾아야 하는 대신 배포 환경에서 한 번의 클릭으로 볼 수 있습니다.

Docs 탭의 위치

Orbit을 열고 프로젝트를 클릭한 후 프로젝트 탭 스트립의 Overview 그룹에서 Docs를 선택합니다.

설정할 것이 없습니다. 프로젝트에 루트에 README가 있는 연결된 저장소가 있으면 탭이 이를 렌더링합니다.

표시되는 파일

Orbit은 연결된 저장소의 기본 브랜치에서 README를 가져옵니다.

GitHub에서는 여러 관례적인 이름을 순서대로 시도합니다: README.md, readme.md, README.MD, README, readme.txt 중 먼저 존재하는 것을 사용합니다. GitLab과 Bitbucket에서는 README.md를 찾습니다.

저장소의 루트만 확인됩니다. 모노레포 앱의 루트 디렉터리를 포함하여 하위 디렉터리 내의 README는 선택되지 않습니다.

렌더링되는 내용

README는 마크다운으로 렌더링됩니다: 제목, 목록, 표, 링크, 인라인 코드, 펜스된 코드 블록이 모두 예상대로 표시됩니다.

README 내의 상대 이미지 경로는 KPanel이 아닌 저장소를 가리키므로, 공급자의 사이트에서 작동하는 이미지가 여기에서 확인되지 않을 수 있습니다. 이미지가 중요하면 절대 URL을 사용합니다.

빈 상태

표시할 내용이 없을 때 두 가지 상태가 내용을 대체합니다:

• No repository connected (저장소가 연결되지 않음), Connect repository 버튼 포함. 먼저 연결합니다: GitHub 저장소 연결, GitLab 저장소 연결 또는 Bitbucket 저장소 연결을 참조합니다.
• No README found (README를 찾을 수 없음), 저장소의 루트에 README.md를 추가하도록 요청하며 공급자에서 생성할 수 있는 링크가 있습니다.

둘 다 공급자로 연결되어 즉시 조치를 취할 수 있으며, 채워진 보기에는 파일을 편집하려는 경우를 위해 View on 링크가 있습니다.

렌더링할 가치가 있는 README 작성

이 탭이 배포 이력 옆에 있기 때문에 Orbit 프로젝트에 가장 유용한 README는 운영 목적의 것입니다. 누군가 프로젝트를 넘겨받은 후 안전하게 무언가를 변경해야 할 때 이를 열게 됩니다.

작동하는 구조:

이것이 무엇인가. 한 단락. 프로젝트가 수행하는 작업과 누구를 대상으로 하는지.

로컬에서 실행. 패키지 관리자를 포함한 정확한 명령어입니다. pnpm install && pnpm dev은 같은 내용을 설명하는 단락을 이깁니다.

환경 변수. 어떤 것이 존재하고 각각이 무엇을 위한 것인지. 값은 절대 포함하지 않습니다: 값들은 저장소의 파일이 아닌 프로젝트의 환경 변수에 속합니다. Orbit의 환경 변수를 참조합니다.

배포 방식. 어떤 브랜치가 프로덕션인지, 태그가 배포되는지 여부, 어떤 게이트가 적용되는지입니다. 탭이 오래될 수 없고 README는 오래될 수 있기 때문에 Orbit 배포 파이프라인 탭을 가리킵니다.

롤백하는 방법. 두 문장과 배포 롤백에 대한 링크입니다. 이것이 사람들이 가장 어려운 순간에 필요한 것이며, 그들이 찾을 곳에 있어야 합니다.

누가 소유하는가. 팀 또는 개인입니다. 프로젝트는 그들을 설정한 사람들보다 오래 지속됩니다.

라이브 상태 배지 추가

README가 여기와 공급자에서 렌더링되므로 배포 상태 배지를 추가할 가치가 있습니다. Orbit은 모든 프로젝트에 대해 하나를 게시합니다.

Settings을 열고 Status badge 카드를 찾습니다. 라이브 미리보기와 3개의 복사 버튼을 표시합니다: 배지 URL, 마크다운 스니펫, HTML 스니펫. README의 맨 위에 마크다운을 붙여넣습니다.

배지는 프로젝트의 프로덕션 환경의 현재 상태를 보고하는 작은 SVG입니다: deployed, building, failed, queued, 또는 no deployments. 인증이 필요하지 않으므로 저장소를 읽는 누구에게나 렌더링되며, KPanel의 프로젝트로 다시 연결됩니다.

이것은 한눈에 프로덕션이 현재 정상 상태인지 보여주는 README를 제공합니다. 이것이 추가할 수 있는 가장 높은 가치를 지닌 한 줄입니다.

신뢰성 유지

프로젝트가 더 이상 가지지 않은 설정을 설명하는 README는 사람들이 신뢰하기 때문에 README가 없는 것보다 더 나쁩니다. 두 가지 습관이 정확성을 유지합니다:

• 복제하지 말고 링크합니다. 빌드 설정, 게이트, 환경 설정 등 KPanel에서 볼 수 있는 모든 것은 재설명하지 말고 링크해야 합니다.
• 같은 풀 요청에서 업데이트합니다. 변경 사항이 프로젝트 실행 방식을 변경하는 경우 README 변경 사항은 나중의 정리 작업이 아닌 해당 풀 요청에 속해야 합니다.

문제 해결

탭에 이전 버전이 표시됩니다. 5분 캐시입니다. 기다렸다가 다시 로드합니다.

README를 찾을 수 없지만 존재합니다. 저장소 루트에 있고 이름이 README.md인지 확인합니다. GitLab과 Bitbucket에서는 이름이 정확히 일치해야 합니다.

저장소가 연결되어 있지만 탭에서 연결되지 않았다고 표시합니다. 예를 들어 공급자 측에서 통합이 제거된 경우 연결이 액세스 권한을 잃을 수 있습니다. 프로젝트 설정에서 다시 연결합니다.

이미지가 로드되지 않습니다. 상대 경로는 여기에서 확인되지 않습니다. 절대 URL을 사용합니다.

배지에 배포가 없다고 표시됩니다. 프로덕션 환경이 성공적인 배포를 한 번도 하지 않았습니다. 한 번 배포하면 업데이트됩니다.

다음으로 이동할 곳

• Orbit 배포 파이프라인, README가 일반적으로 설명하려고 하는 내용의 라이브 버전.
• Orbit 프로젝트 설정 (상태 배지 및 나머지 설정).
• Orbit의 환경 변수 (README가 포함해야 할 값).