mirror of
https://github.com/asdf-vm/asdf.git
synced 2024-12-25 21:05:07 -07:00
159 lines
6.2 KiB
Markdown
159 lines
6.2 KiB
Markdown
# asdf
|
|
|
|
`asdf` 코어 기여 가이드.
|
|
|
|
## 초기 설정
|
|
|
|
Github의 `asdf`를 fork하거나 clone하세요:
|
|
|
|
```shell
|
|
# clone your fork
|
|
git clone https://github.com/<GITHUB_USER>/asdf.git
|
|
# or clone asdf
|
|
git clone https://github.com/asdf-vm/asdf.git
|
|
```
|
|
|
|
코어 개발을 위한 툴들은 이 리포지토리의 `.tool-versions`에 있습니다. 만약 `asdf`가 직접 관리하기를 바라신다면, 다음 플러그인들을 설치하세요:
|
|
|
|
```shell
|
|
asdf plugin add bats https://github.com/timgluz/asdf-bats.git
|
|
asdf plugin add shellcheck https://github.com/luizm/asdf-shellcheck.git
|
|
asdf plugin add shfmt https://github.com/luizm/asdf-shfmt.git
|
|
```
|
|
|
|
`asdf`를 개발하기 위한 버전들을 설치하세요:
|
|
|
|
```shell
|
|
asdf install
|
|
```
|
|
|
|
로컬 머신에서 개발 도구를 손상시킬 수 있는 기능을 개발 중일 경우 `asdf`를 사용하지 않는 것이 _좋을 수_ 있습니다. 개발 도구들의 원본 목록입니다:
|
|
|
|
- [bats-core](https://github.com/bats-core/bats-core): Bash 또는 POSIX 준수 스크립트를 단위 테스트하기 위한 Bash 자동화 테스트 시스템.
|
|
- [shellcheck](https://github.com/koalaman/shellcheck): 셸 스크립트 정적 분석 도구.
|
|
- [shfmt](https://github.com/mvdan/sh): Bash를 지원하는 셸 parser, formatter, interpreter; shfmt 포함
|
|
|
|
## 개발
|
|
|
|
만약 설치된 `asdf`에 영향 없이 변화들을 테스트해보시고 싶으시다면, `$ASDF_DIR` 변수를 리포지토리를 clone한 경로에 지정하시고, 그 다음 임시로 `bin`와 `shims` 디렉토리들을 경로 앞에 추가하세요.
|
|
|
|
원격 리포지토리에 커밋 혹은 push하기 전에, 당신의 코드를 format, lint, 그리고 locally test하세요. 다음 스크립트/명령어들을 사용하세요:
|
|
|
|
```shell
|
|
# Lint
|
|
./scripts/lint.bash --check
|
|
|
|
# Fix & Format
|
|
./scripts/lint.bash --fix
|
|
|
|
# Test: all tests
|
|
./scripts/test.bash
|
|
|
|
# Test: for specific command
|
|
bats test/list_commands.bash
|
|
```
|
|
|
|
::: tip
|
|
|
|
**테스트 추가!** - 새로운 기능들과 버그 수정들의 리뷰 속도 향상을 위해 테스트들은 **필수적**입니다. 풀 리퀘스트 요청을 만드시기 전에 새로운 코드 경로들을 추가해주세요. [bats-core 문서](https://bats-core.readthedocs.io/en/stable/index.html) 참조
|
|
|
|
:::
|
|
|
|
### Gitignore
|
|
|
|
다음은 `asdf-vm/asdf` 리포지토리에 `.gitignore` 파일입니다. 우리는 프로젝트에 관련된 특정한 파일들을 무시합니다. 운영체제, 툴, workflows에 관련된 파일들은 글로벌 `.gitignore` 설정에서 무시되어야합니다, [더 보기](http://stratus3d.com/blog/2018/06/03/stop-excluding-editor-temp-files-in-gitignore/).
|
|
|
|
@/../.gitignore
|
|
|
|
### `.git-blame-ignore-revs`
|
|
|
|
`asdf`는 `.git-blame-ignore-revs` 사용해 blame 실행에서 잡음을 줄입니다. 더 많은 정보 [git blame 문서](https://git-scm.com/docs/git-blame).
|
|
|
|
다음과 같이 `git blame`과 `.git-blame-ignore-revs`을 사용:
|
|
|
|
```sh
|
|
git blame --ignore-revs-file .git-blame-ignore-revs ./test/install_command.bats
|
|
```
|
|
|
|
선택적으로, 수동적으로 파일을 제공하는 대신 모든 `blame`에서 해당 파일을 사용하도록 설정:
|
|
|
|
```sh
|
|
git config blame.ignoreRevsFile .git-blame-ignore-revs
|
|
```
|
|
|
|
IDE들에서 이 파일을 사용하도록 설정할 수 있습니다. 예를 들어, VSCode를 사용하실 경우 ([GitLens](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens)와 함께), 다음을 `.vscode/settings.json`에 추가하세요:
|
|
|
|
```json
|
|
{
|
|
"gitlens.advanced.blame.customArguments": [
|
|
"--ignore-revs-file",
|
|
".git-blame-ignore-revs"
|
|
]
|
|
}
|
|
```
|
|
|
|
## Bats 테스팅
|
|
|
|
로컬 테스트 실행:
|
|
|
|
```shell
|
|
./scripts/test.bash
|
|
```
|
|
|
|
테스트 작성 전 **반드시 읽기**:
|
|
|
|
- `test/`에 존재하는 테스트들
|
|
- [bats-core 문서](https://bats-core.readthedocs.io/en/stable/index.html)
|
|
- `scripts/test.bash`에 존재하는 Bats 설정들
|
|
|
|
### Bats 팁
|
|
|
|
Bats 디버깅은 때에 따라 어려울 수 있습니다. 디버깅 단순화를 위해, `-t` flag로 TAP output을 사용하여 테스트 실행 중 결과물 출력을 위한 특별한 파일 디스크립터 `>&3`를 사용할 수 있습니다. 예시:
|
|
|
|
```shell
|
|
# test/some_tests.bats
|
|
|
|
printf "%s\n" "Will not be printed during bats test/some_tests.bats"
|
|
printf "%s\n" "Will be printed during bats -t test/some_tests.bats" >&3
|
|
```
|
|
|
|
bats-core의 더 자세한 문서 [Printing to the Terminal](https://bats-core.readthedocs.io/en/stable/writing-tests.html#printing-to-the-terminal).
|
|
|
|
## 풀 리퀘스트, 릴리스 & 관습적 커밋
|
|
|
|
`asdf`는 자동화 배포 툴 [Release Please](https://github.com/googleapis/release-please)를 사용하여 자동으로 [SemVer](https://semver.org/) 버전을 올리고 [변동사항](https://github.com/asdf-vm/asdf/blob/master/CHANGELOG.md)을 작성합니다. 이 정보들은 지난 배포들로부터 커밋 history를 읽음으로써 결정됩니다.
|
|
|
|
[유의적 커밋 메세지](https://www.conventionalcommits.org/)는 기본 브랜치의 커밋 메세지 형식이 되는 풀 리퀘스트 제목의 형식을 정의합니다. 이것은 GitHub Action에서 강제됩니다 [`amannn/action-semantic-pull-request`](https://github.com/amannn/action-semantic-pull-request).
|
|
|
|
관습적인 커밋 다음 형식을 따릅니다:
|
|
|
|
```
|
|
<type>[optional scope][optional !]: <description>
|
|
|
|
<!-- examples -->
|
|
fix: some fix
|
|
feat: a new feature
|
|
docs: some documentation update
|
|
docs(website): some change for the website
|
|
feat!: feature with breaking change
|
|
```
|
|
|
|
`<types>`의 모든 목록: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`.
|
|
|
|
- `!`: 주요한(breaking) 변화들을 나타냅니다
|
|
- `fix`: 새로운 SemVer `patch`을 만듭니다
|
|
- `feat`: 새로운 SemVer `minor`을 만듭니다
|
|
- `<type>!`: 새로운 SemVer `major`을 만듭니다
|
|
|
|
풀 리퀘스트 제목은 반드시 이 형식을 따라야 합니다.
|
|
|
|
::: tip
|
|
|
|
풀 리퀘스트 제목을 관습적 커밋 메세지 형식을 사용하세요.
|
|
|
|
:::
|
|
|
|
## Docker 이미지
|
|
|
|
[asdf-alpine](https://github.com/vic/asdf-alpine)와 [asdf-ubuntu](https://github.com/vic/asdf-ubuntu) 프로젝트들은 asdf 툴들의 Dockerized 이미지들을 제공하기 위해 진행되고있습니다. 개발 서버의 베이스 혹은 프로덕션 앱들을 위해 docker 이미지들을 사용할 수 있습니다.
|