어느 날 회사에서 이런 요청을 받았다:
@flavono123 cc. @someone @anotherone
github에서 PR template에 다음 사항 추가해주실 수 있을까요? 모두에게 적용하는 걸로요(즉 전사 공통)
<생략>
PR 템플릿
PR 템플릿의 존재는 이미 알고 있었다. 말그대로 PR 생성 시 초안이 될 내용의 마크다운을 작성해두는 것이다.
여러 방법이 있지만 git 프로젝트 루트에 PULL_REQUEST_TEMPLATE 파일을 만들어 쓰고 있었다. 개인적으로 레포 단위로 사용했고, 필요하다고 공감해주는 팀원들에게 구두로 전파하는 수준이었다. 하지만 이번엔 조직 수준에서 특정 양식을 “강제”하고 싶다는 요구사항을 받았다.
oraganization/.github
조직 수준의(org wide) 기본 PR 템플릿을 만들기 위한 방법은:
1.
.github 라는 이름의 새 레포를 “퍼블릭”으로 만들고
2.
(개별 레포와 같은 방식으로)PULL_REQUEST_TEMPLATE을 만든다.
이렇게 하면 기본 값에 해당하는 PR 템플릿이 생기기 때문에, 레포에 별도의 설정이 없다면 이 템플릿을 사용하게 된다(레포에 구성되어 있다면 그것을 사용한다, ovewrite).
실제로 회사 요청에 대한 처리는 이것으로 끝났다. 하지만 느낀점과 뭔가 더 하고 싶다는 아쉬움이 있었다.
일단 .github 라는 레포는 퍼블릭이어야 한다. 왜? 그리고 PR 템플릿과 같은 종류의 파일을 커뮤니티 상태 파일(community health file)이라고 한다. 단순히 PR 템플릿을 조직에 강제하는 역할 뿐만 아니라 더 큰 무언가를 함의한다고 느꼈다.
조직 수준 “프라이빗” PR 템플릿을 만들 수 있게(
템플릿을 고를 수 있게) 기능을 지원해달라는 이런 요청이 있다. 아직 github 측의 의견이 달리지 않았는데… 단순히 우선순위가 낮아 개발되지 않는 기능 같기도 하다.
템플릿을 고를 수 있게) 기능을 지원해달라는 이런 요청이 있다. 아직 github 측의 의견이 달리지 않았는데… 단순히 우선순위가 낮아 개발되지 않는 기능 같기도 하다.커뮤니티 상태 파일(community health file)
앞서 말한 듯, PR 템플릿은 커뮤니티 상태 파일 중 하나이다. 커뮤니티 상태 파일의 의도는 오픈소스 프로젝트로써 건전하고 협업적인(healthy and collaborative) 지침, 템플릿을 제공하여 프로젝트의 투명성, 모범 사례와 협업을 촉진 하기 위함이다.
돈 내고 플랜을 사용하는 고객도(팀 플랜 야이야기이다, 엔터프라이즈 안 써 봄), 심지어 “프라이빗” 레포에도 적용되는 내용을, “공개(public)” 하게 한다는 점이 고무적이다.
지원 파일 유형
위 링크 페이지에 있는, 커뮤니티 상태 파일의 유형과 설명을 간단히 적는다. 각각의 자세한 사례는 없지만, 파일 이름만 보아도 의도를 어느 정도 가늠할 수 있다:
•
CODE_OF_CONDUCT.md: 커뮤니티 참여에 대한 행동 강령을 정의한다.
•
CONTRIBUTING.md: 프로젝트의 기여 가이드를 정의한다.
•
토론(discussion) 카테고리 양식: 새 토론을 열 때 카테고리별 템플릿.
•
FUNDING.yml: 스폰서 버튼을 표시하여 펀딩 옵션의 가시성을 제공한다.
•
GOVERNANCE.md: 프로젝트 거버넌스(관리)에 대해 표시한다.
•
이슈, PR 템플릿: 새 이슈나 PR을 열 때 템플릿.
•
SECURITY.md: 프로젝트의 보안 취약점을 보고하는 방법에 대한 지침이다.
•
SUPPORT.md: 프로젝트를 도울 수 있는 방법에 대한 지침이다.
그리고 라이선스 파일을 기본 값을 정할 수 없다.
사실 모든 파일이 각자 비즈니스에 꼭 필요하지 않을 것이다. 하지만 생각해볼 지점들은 많다. 엔지니어다운 생각이지만, 대부분 프로젝트는 오픈 소스를 지향해야 한다고 생각한다(대부분의 프라이빗 프로젝트는, 딱히 개발 속도를 저해하지 않는, “부끄러운” 보안적인 이유로 공개하지 않는 것이라 생각한다). 개인적인 프로젝트에서 참고해볼만하다.
좋은 PR/이슈 템플릿?
여러 파일 유형 중, 나의 경우처럼, 회사에서도 적용하기 좋은 PR 템플릿에 대해서 더 알아보자. 정답이 없는 영역이다. “pr template best practices”로 검색해도 여러가지 컨텐츠가 나온다. 너무나(??) 옳은 이야기를 하고 있기 때문에 더 추상적이기도 하다.
우리 회사의 경우, semver 스타일의 버전을 적도록 유도하는 템플릿을 썼다. 배포 시 여러 개발자가 수정한 여러 서비스의 의존 관계가 어지러웠다. 이를 해결해보려는 시도로 출발했다.
기본적으로 semver 연월일의 타임스탬프를 붙이는 것을 따르되, 언어마다 제한 되는 부분은 예외를 두었다. (공개가 되어 있긴 하지만) 몇몇 회사 내부 컨텍스트가 필요한 부분은 삭제했다:
## `vX.Y.Z-yymmdd`
* Please use `vX.Y.Z-yymmdd` format e.g. `v2.6.0-231120`
* `yymmdd` means the date of QA in stage environment, every Monday
## `vX.Y.Z`
* For `go` lang, version should start with `v` and other information cannot be added for packaging
## `x.y.z`
* For `npm`, it is strict. It is necessary to add date as a meta data in package.json
# Please check
* [ ] Did you follow the version format for your language?
* [ ] Did you let people know the deployment in the appropriate slack channel?
Markdown
복사
다른 예시로, 현재 운영 중인 오픈 소스 프로젝트(살짝 기여했던 karpenter이다)의 예시를 한번 살펴보자:
# Description
<!--
🛑 Please open an issue first to discuss any significant work and flesh out details/direction - we would hate for your time to be wasted.
Consult the [CONTRIBUTING](https://github.com/aws-ia/terraform-aws-eks-blueprints/blob/main/CONTRIBUTING.md#contributing-via-pull-requests) guide for submitting pull-requests.
A brief description of the change being made with this pull request.
-->
### Motivation and Context
<!-- What inspired you to submit this pull request? -->
- Resolves #<issue-number>
### How was this change tested?
- [ ] Yes, I have tested the PR using my local account setup (Provide any test evidence report under Additional Notes)
- [ ] Yes, I have updated the [docs](https://github.com/aws-ia/terraform-aws-eks-blueprints/tree/main/docs) for this feature
- [ ] Yes, I ran `pre-commit run -a` with this PR
### Additional Notes
<!-- Anything else we should know when reviewing? -->
Markdown
복사
동기와 컨텍스트 부분에서 대부분의 설명을 참조 이슈로 넘긴다. github 프로젝트로써 이슈 생성 → PR의 프로세스를 만들기 위한 좋은 방법이라 생각된다(이슈 템플릿도 같이 살펴보자).
그 외에 신경 쓰는 부분은 테스트이다. 모든 수정에 대하여 꼭 필요한, 안 했을 경우 여러 사람이 귀찮아질, 것들에 대한 체크리스트가 있다.
조직 프로필 구성하기
.github 레포에서, 커뮤니티 상태 파일 뿐만 아니라, 조직에 대한 프로필 구성도 가능하다. <org>/.github/profile/README.md 에 파일을 위치시키면 된다.
프로필은, 조직 멤버에게만 노출할 목적으로, “프라이빗” 구성을 할 수 있다(<org>/.github-private/profile/README.md). PR 템플릿은 안되는데 이건 프라이빗을 지원한다는게 좀 의아하다
습득 교훈
•
github 조직 전체에 PR 템플릿을 강제할 목적으로 커뮤니티 상태 파일을 만들었다.
•
커뮤니티 상태 파일은(<org>/.github/… ), PR/이슈 템플릿 뿐만 아니라, 오픈 소스 프로젝트로써 협업을 도와주는 여러 파일을 조직 레포 기본 값이 되게 한다.
◦
이 파일을 저장하는 레포는 “퍼블릭”으로 만들어야만 한다.