Glossary
source-repo 문서에서 반복해서 쓰는 delivery, CI/CD, packaging 용어를 짧게 정리합니다. 자세한 운영 기준은 각 delivery 문서를 봅니다.
1. CI/CD 기본 용어
| Term | Meaning | In this repo |
|---|---|---|
| CI | Continuous Integration. 변경이 들어왔을 때 code, test, package build, app build가 깨지지 않았는지 자동으로 확인하는 흐름입니다. | Source repo CI는 deployable artifact를 만들 수 있는지 검증합니다. 실제 Kubernetes 배포는 하지 않습니다. |
| CD | Continuous Delivery 또는 Continuous Deployment. 배포 가능한 artifact를 환경으로 전달하거나 배포하는 흐름입니다. | source-repo는 image tag/digest, package version, migration 필요 여부를 CD repo에 넘깁니다. Environment promotion과 rollback은 CD repo 책임입니다. |
| Gate | 다음 단계로 넘어가기 전에 통과해야 하는 검사 묶음입니다. | PR required gate가 실패하면 merge하지 않습니다. Release gate가 실패하면 package나 release image를 publish하지 않습니다. |
| Artifact | Source code에서 만들어져 다른 단계가 소비하는 결과물입니다. | npm package, Python wheel, Rust crate, Go module tag, C/Conan package, firmware image, container image가 대표 artifact입니다. |
| Publish | Artifact를 registry나 artifact repository에 올려 다른 사람이 가져갈 수 있게 만드는 작업입니다. | PR에서는 보통 build만 하고 publish하지 않습니다. Release tag와 approval 뒤 publish합니다. |
2. Branch와 Release 용어
| Term | Meaning | In this repo |
|---|---|---|
| Issue | 작업을 시작하기 위한 최소 기록입니다. | 변경 목적, 범위, 검증 방법, impact를 남기는 anchor로 사용합니다. |
| Pull request | Branch의 변경을 main에 반영하기 전에 CI와 self-review를 수행하는 change set 단위입니다. |
PR은 항상 사람이 깊게 review한 단위가 아닙니다. Human review는 impact에 따라 요구합니다. |
| Trunk | 팀이 기준으로 삼는 중심 branch입니다. | main이 trunk입니다. 짧은 작업 branch를 pull request로 검증한 뒤 main에 자주 합칩니다. |
| Protected branch | 직접 push를 막고, 정해진 merge 조건을 통과한 pull request만 merge할 수 있게 보호한 branch입니다. | main은 protected trunk입니다. 기본 merge 조건은 required CI, 작성자 self-review, squash merge입니다. Human review는 impact에 따라 요구합니다. |
| Self-review | 작성자가 merge 전에 자신의 diff, secret, test, impact check를 직접 확인하는 단계입니다. | 모든 PR의 기본 통과 기준입니다. |
| Impact check | PR 변경이 clinical behavior, public contract/API, migration/data, release/security 경계에 영향을 주는지 짧게 표시하는 확인입니다. | 정식 SaMD risk analysis가 아니라 human review 필요 여부를 판단하기 위한 triage입니다. |
| Risk-based review | 변경 위험도에 따라 human review 필요 여부를 정하는 방식입니다. | Clinical/risk logic, public API, contract, migration, CI/CD, release, security 변경은 human review가 필요합니다. 실제 SaMD risk analysis는 release, design, clinical review gate에서 다룹니다. |
| Squash merge | Pull request 안의 여러 commit을 하나의 commit으로 합쳐 target branch에 넣는 방식입니다. | 작은 WIP commit은 PR 안에 남기고, main에는 검증된 change set 하나만 남겨 history를 읽기 쉽게 만듭니다. |
| Release tag | 특정 commit을 release 기준점으로 고정하는 Git tag입니다. | vX.Y.Z 형식을 사용합니다. 예를 들어 v0.1.0은 package, image, firmware artifact를 같은 release baseline으로 묶습니다. |
| Dev image | Release image가 아니라 통합 검증, preview, troubleshooting을 위해 만드는 container image입니다. | main merge 뒤 dev-<run>-g<sha>처럼 source revision이 보이는 tag로 publish할 수 있습니다. |
| Release image | Release tag와 approval을 기준으로 publish하는 container image입니다. | Production이나 regulated environment가 소비할 수 있으므로 tag/digest, source revision, SBOM, provenance를 함께 남깁니다. |
3. Commit 용어
| Term | Meaning | In this repo |
|---|---|---|
| Conventional Commits | <type>(<scope>): <summary> 형태로 commit message를 쓰는 관례입니다. |
PR title과 squash commit title은 이 형식을 따릅니다. |
| Commit type | 변경 성격을 나타내는 prefix입니다. | 기본은 feat, fix, docs, test, refactor, chore를 사용하고, 필요할 때 ci, build, perf, revert를 씁니다. |
| Scope | Commit이 영향을 주는 영역을 짧게 나타내는 선택 항목입니다. | docs(workflow): ..., fix(demo): ..., ci(release): ...처럼 씁니다. |
4. Package와 Container 용어
| Term | Meaning | In this repo |
|---|---|---|
| Package | 다른 code가 dependency로 가져다 쓰는 재사용 단위입니다. | npm package, Python wheel, Rust crate, Go module, Conan package가 package입니다. Consumer build에 영향을 주므로 release publish를 기본으로 둡니다. |
| Container image | App을 실행할 수 있도록 runtime, dependency, entrypoint를 묶은 배포 단위입니다. | Package가 정상이어도 image가 정상이라는 뜻은 아닙니다. Dockerfile, runtime dependency, healthcheck, non-root user는 image build/test에서 확인합니다. |
| Registry | Package나 container image를 저장하고 내려받는 저장소입니다. | Package registry로 Nexus를 사용하고, container image registry로 GHCR 같은 container registry를 사용할 수 있습니다. |
| Nexus | 사내 package registry와 artifact repository 역할을 하는 저장소입니다. | npm, PyPI, Cargo, Conan, raw firmware artifact를 저장합니다. Repository 기준은 Nexus를 봅니다. |
5. Platform 용어
| Term | Meaning | In this repo |
|---|---|---|
| Platform-neutral artifact | OS나 CPU architecture가 달라도 같은 artifact를 사용할 수 있는 경우입니다. | Pure Python wheel, npm package, Rust crate source package는 대체로 platform-neutral로 봅니다. |
| Platform-specific artifact | OS, CPU architecture, toolchain에 따라 결과물이 달라지는 artifact입니다. | Rust Python wheel, C/Conan binary package, firmware image, container image가 여기에 속합니다. |
| CI matrix | 같은 job을 여러 platform, language version, target 조합으로 반복 실행하는 설정입니다. | Rust Python wheel을 linux/amd64와 linux/arm64 둘 다 만들 때 platform별 matrix build가 필요합니다. |
| SBOM | Software Bill of Materials. Artifact 안에 어떤 dependency와 component가 들어 있는지 기록한 목록입니다. | Release image처럼 외부에서 소비하는 artifact는 SBOM을 남겨 취약점 추적과 audit에 사용합니다. |
| Provenance | Artifact가 어떤 source revision, workflow, build 환경에서 만들어졌는지 설명하는 출처 정보입니다. | SaMD나 regulated 환경에서는 release artifact가 어디서 왔는지 추적할 수 있어야 하므로 provenance가 중요합니다. |