# 기여와 릴리스 > stdlib-only runtime, pytest gate, redaction scan, pre-push hook, version 산출, changelog, tag owner approval, Conventional Commits를 설명합니다. - Repository: local/master-ops-with-local-mogui-ADE-orchestrator - Human docs: https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3 - Complete Markdown: https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/llms-full.txt ## Source Files - `local-mogui-ade-orchestrator:CONTRIBUTING.md` - `local-mogui-ade-orchestrator:docs/internal/release-runbook.md` - `local-mogui-ade-orchestrator:CHANGELOG.md` - `local-mogui-ade-orchestrator:scripts/next-version` - `local-mogui-ade-orchestrator:hooks/pre-push` - `local-mogui-ade-orchestrator:tests/test_reference_command_table.py` - `local-master-ops:CHANGELOG.md` --- --- title: "기여와 릴리스" description: "stdlib-only runtime, pytest gate, redaction scan, pre-push hook, version 산출, changelog, tag owner approval, Conventional Commits를 설명합니다." --- `local-mogui-ade-orchestrator`의 릴리스 표면은 stdlib-only 런타임, `pytest` 테스트 게이트, `gitleaks` 기반 redaction 래퍼, opt-in `pre-push` hook, `MAJOR.MINOR.BUILD` 버전 산출 스크립트, 수동 태그 승인 절차로 구성된다. `local-master-ops`는 설치 템플릿으로 별도 `TEMPLATE-VERSION`과 `CHANGELOG.md`를 가진다. ## 기여 기준 런타임 코드는 Python 표준 라이브러리만 전제로 한다. 테스트 실행에는 `pytest`가 필요하며, 기여자는 변경 전후를 설명할 수 있는 실패 테스트를 우선 둔다. ```console PYTHONPATH=src python3 -m pytest tests -q ``` 문서 변경은 테스트가 없어도 된다. 이 경우 pull request에는 기존 문구가 무엇을 잘못 설명했는지 적는다. ### 커밋 형식 커밋 메시지는 영어 Conventional Commits를 사용한다. ```text feat(scope): add dispatch report fix(scope): close undecidable gate path docs(scope): clarify redaction scope ``` 커밋에는 무엇이 바뀌었는지와 왜 필요했는지를 함께 적는다. PR은 squash merge를 전제로 한다. AI agent가 작성한 커밋에는 해당 모델을 명시하는 `Co-Authored-By` trailer를 붙이는 관례가 있다. ## 테스트와 게이트 | 표면 | 명령 | 판정 | | --- | --- | --- | | 테스트 게이트 | `PYTHONPATH=src python3 -m pytest tests -q` 또는 릴리스 런북의 `PYTHONPATH=src uv run pytest tests -q` | 실패 시 merge 또는 release 중단 | | 공개 CLI 표면 | `local-mogui-ade-orchestrator:tests/test_reference_command_table.py` | `scripts/` 실행 파일과 `docs/public/reference.md` 표가 어긋나면 실패 | | 템플릿 도구명 게이트 | `bash master-ops/scripts/test-tool-naming.sh` | `ctx.` 같은 호출 불가능한 도구명이 문서/skill에 남으면 실패 | | redaction scan | `./scripts/redaction-scan.sh` | exit `0` clean, `1` finding, `2` cannot decide | | redaction inventory | `./scripts/redaction-inventory` | exit `0` uncovered 후보 없음, `1` 후보 발견, `2` 판단 불가 | 여러 스크립트는 exit code `2`를 “판단 불가”로 사용한다. crash나 사용법 오류를 finding처럼 보이게 만들면 호출자가 실패 원인을 잘못 해석한다. 새 failure path를 추가할 때는 각 스크립트의 header와 reference row를 먼저 확인한다. ## Redaction 게이트 `local-mogui-ade-orchestrator:scripts/redaction-scan.sh`는 `gitleaks`를 matching engine으로 사용한다. 래퍼가 담당하는 부분은 scan scope 제한, commit message scan, 조직별 rule 병합, coverage 출력이다. ```console ./scripts/redaction-scan.sh ./scripts/redaction-scan.sh --staged ./scripts/redaction-scan.sh --range A..B ./scripts/redaction-scan.sh --commit-messages A..B ``` 조직별 rule은 repository에 commit하지 않는다. checkout별 파일을 `REDACTION_EXTRA_PATTERNS`로 지정한다. ```text id|description|regex ``` `REDACTION_REQUIRE_EXTRA=1` 또는 `--require-extra`를 사용하면 조직별 rule이 없거나 비어 있을 때 exit `2`로 중단한다. 기본 scan은 organization rule 없이도 generic pattern만으로 실행될 수 있으므로, green output의 `org-rules=` 값을 확인해야 한다. ```console REDACTION_REQUIRE_EXTRA=1 \ REDACTION_EXTRA_PATTERNS=~/.config/redaction-extra.txt \ ./scripts/redaction-scan.sh ``` `redaction-inventory`는 scan의 반대 질문을 묻는다. “rule이 잡은 것”이 아니라 “tracked tree에 있지만 어떤 rule도 덮지 않는 token 후보”를 보고한다. 후보 발견 exit `1`은 정상 triage 상태이며, secret 판정 자체가 아니다. 릴리스에서는 exit `2`만 판단 불가로 보고 차단한다. redaction 도구는 repository content를 읽는다. PR title, PR body, review comment, release note, issue text, forge UI에 직접 입력한 문장은 repository scan 범위가 아니다. `local-master-ops:scripts/conversation-redaction-scan`은 PR/issue 대화 표면을 별도로 검사하는 템플릿 도구다. ## Pre-push hook `local-mogui-ade-orchestrator:hooks/pre-push`는 clone별 opt-in hook이다. ```console git config core.hooksPath hooks ``` hook은 Git이 stdin으로 전달한 pushed ref range를 읽고, 가능한 경우 각 range에 대해 다음 scan을 실행한다. ```console scripts/redaction-scan.sh --range "$base..$local_sha" ``` 새 ref나 fetch되지 않은 remote tip처럼 range 기준점을 직접 사용할 수 없는 경우에는 `origin/main`과의 merge-base를 시도한다. 어떤 range도 확정되지 않으면 tracked tree scan으로 fallback한다. hook은 테스트 suite를 실행하지 않는다. 빠른 redaction check만 담당한다. ## 릴리스 절차 릴리스 런북은 orchestrator release를 `MAJOR.MINOR.BUILD` 형식으로 자른다. `MAJOR.MINOR`은 owner-managed milestone이며 자동화가 올리지 않는다. `BUILD`는 `refs/remotes/origin/main`의 commit count에서 산출한다. ```console git fetch origin main --tags ``` shallow clone이면 먼저 unshallow를 수행한다. ```console git fetch --unshallow origin main --tags ``` ```console version="$(./scripts/next-version)" printf '%s\n' "$version" ``` `origin/main` ref가 없거나 shallow repository이면 `scripts/next-version`은 exit `2`로 중단한다. ```console git add -A ``` redaction scanner는 tracked content를 읽는다. 새 파일이 unstaged 상태이면 scan 대상에서 빠질 수 있다. ```console set -e PYTHONPATH=src uv run pytest tests -q bash master-ops/scripts/test-tool-naming.sh ./scripts/redaction-scan.sh rc=0 ./scripts/redaction-inventory || rc=$? if [ "$rc" -ne 0 ]; then [ "$rc" -eq 1 ] || exit "$rc"; fi ``` `CHANGELOG.md`에 `v${version}` 릴리스 노트가 있고, 링크와 날짜 문구가 맞는지 확인한다. ```console [ -n "${version:-}" ] || exit 1 git tag "v${version}" ``` 태그 생성과 tag push는 owner의 명시적 승인 뒤에만 수행한다. 자동화가 tag를 만들거나 push하지 않는다. ## 버전과 changelog 경계 `local-mogui-ade-orchestrator:CHANGELOG.md`는 orchestrator release history를 기록한다. 형식은 Keep a Changelog 계열이며, release versioning은 `MAJOR.MINOR.BUILD`다. major version이 `0`인 동안 CLI flag, file format, module interface는 minor release에서 바뀔 수 있다. 이 표면 위에 통합을 만들면 version pinning이 필요하다. `local-master-ops` 템플릿은 별도 version stream을 가진다. `local-master-ops:TEMPLATE-VERSION`은 현재 템플릿 tag string을 담고, `local-master-ops:CHANGELOG.md`는 템플릿 변경 내역을 기록한다. onboarding이 생성한 operations repository는 템플릿의 copy이므로 기존 설치가 자동 갱신되지 않는다. | 구분 | 위치 | 갱신 시점 | 의미 | | --- | --- | --- | --- | | Orchestrator release | `local-mogui-ade-orchestrator:CHANGELOG.md` | orchestrator release cut | runtime, scripts, public docs의 변경 | | Template version | `local-master-ops:TEMPLATE-VERSION` | template release cut | 새 ops repository가 복사할 template stamp | | Template changelog | `local-master-ops:CHANGELOG.md` | `master-ops/` 변경과 release | 설치 템플릿 변경, upgrade 판단 근거 | | Installed manifest | `local-master-ops:MANIFEST.json` | manifest regeneration 또는 release | 설치 대상 file set과 template version stamp | `master-ops/`를 바꾸는 변경은 같은 변경 안에서 `local-master-ops:CHANGELOG.md`의 `## Unreleased`에 항목을 추가한다. `TEMPLATE-VERSION`은 merge 때가 아니라 release cut 때 이동한다. ## CI 범위 `local-mogui-ade-orchestrator:.github/workflows/gates.yml`은 PR과 `main` push에서 테스트 job과 redaction job을 실행한다. Ubuntu와 macOS 테스트는 blocking이고, Windows leg는 measurement-only로 유지된다. CI redaction은 repository에 committed된 rule set만 사용한다. 조직별 `REDACTION_EXTRA_PATTERNS` 파일은 repository에 없으므로 전체 publish scan은 local gate에서 수행한다. ## 실패 신호 | 증상 | 의미 | 조치 | | --- | --- | --- | | `next-version: origin/main is unavailable` | build 산출 기준 ref가 없음 | `git fetch origin main --tags` 후 재실행 | | `next-version: shallow clone detected` | commit count가 release 기준으로 불완전함 | `git fetch --unshallow origin main --tags` | | `redaction-scan: WARNING ... org-rules=0` | generic rule만 적용됨 | release/publish 전 `REDACTION_EXTRA_PATTERNS`와 require flag 확인 | | `redaction-scan` exit `1` | finding 존재 | 수정하거나 `.gitleaksignore` fingerprint 또는 `config/gitleaks.toml` allowlist로 명시적 예외 처리 | | `redaction-scan` exit `2` | 판단 불가 | tool, config, rule compile, range resolve 문제를 먼저 해결 | | `redaction-inventory` exit `1` | uncovered 후보 존재 | 후보를 triage하고 필요한 token은 조직 rule 또는 baseline에 반영 | | `test-tool-naming.sh` exit `1` | 문서/skill이 호출 불가능한 tool name을 노출함 | `mcp__ctx__` 형식으로 고침 | ## Related pages `redaction-scan.sh`, `redaction-inventory`, 조직 rule, commit message scan, pre-push hook 범위를 더 자세히 정리합니다. 공개 `scripts/` 명령, option, exit code, reference table 검증 방식을 확인합니다. `master-ops` template version, manifest, upgrade, template-check surface를 확인합니다. preflight, redaction 판단 불가, placement, model probe 실패 신호를 증상별로 확인합니다.