오픈소스 프로젝트 폴리싱

오픈소스 프로젝트 폴리싱은(는) 무엇을 하나요?

목표

기존 프로젝트 폴더를 고품질 오픈소스 저장소로 변환합니다. 공개 문서, 커뮤니티 파일, 저장소 메타데이터, Git/GitHub 설정을 개선하면서 원본 소스 코드는 보존합니다.

엄격한 경계

• 사용자가 명시적으로 요청하지 않는 한, 원본 제품/소스 코드, 생성된 로직, 테스트, 노트북, 에셋, 런타임 동작을 수정하지 않습니다.
• 허용된 변경은 프로젝트 관련 메타데이터와 문서(README, LICENSE, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, CHANGELOG, SUPPORT, CITATION, 이슈/PR 템플릿, 릴리스 노트, 배지, .gitignore, .gitattributes, .editorconfig, GitHub 워크플로우/문서 스캐폴딩)로 제한됩니다.
• README 또는 공개 문서에 /home/<user>/..., /Users/<user>/..., 드라이브 문자 경로, 개인 작업공간 이름, 다운로드 폴더, 시스템별 절대 프로젝트 경로와 같은 사용자별 로컬 머신 경로를 절대 포함하지 않습니다. 대신 상대 경로, $HOME, <repo>, 또는 플레이스홀더를 사용합니다.
• 라이선스가 없고 사용자 선호도가 명시되지 않은 경우 기본적으로 MIT 라이선스를 사용합니다.
• Git 원격이 없는 폴더에는 기본적으로 자동 공개 GitHub 게시를 사용합니다. 대상 소유자/이름이 명확하지 않으면 확인한 후 공개 원격 저장소를 생성하고, 시크릿 검사를 통과한 후 문서 전용 변경 사항을 푸시합니다.
• 네트워크/GitHub 명령이 실패하면 설정된 로컬 프록시로 한 번 재시도한 후 원격 단계가 차단된 것으로 간주합니다.
• 기존 문서와 커뮤니티 파일은 가능한 한 보존하고, 유용한 콘텐츠를 교체하기보다 점진적으로 개선합니다.

누락 시 명확히 할 입력 사항

되돌릴 수 없거나 공개적인 작업에 실질적인 영향을 미치는 정보에 대해서만 질문합니다.

1. 대상 범위: 작업공간 프로젝트 경로, 또는 이미 명확한 경우 현재 폴더.
2. 공개 신원: 폴더와 인증된 GitHub 계정으로 추론할 수 없는 경우, 원격 저장소를 만들기 전에 GitHub 소유자/저장소 이름.
3. 라이선스 재정의: 기존 라이선스가 있으면 사용하고, 없으면 사용자가 다른 라이선스를 요청하지 않는 한 기본적으로 MIT를 적용합니다.
4. 프로젝트 포지셔닝: 코드/문서에서 추론할 수 없는 경우, 한 문장짜리 가치 제안, 대상 사용자, 성숙도.
5. 소스 코드 편집: 기본적으로 금지; 메타데이터/문서를 넘어서는 수정은 묻습니다.

절차

1. 프로젝트 상태 감사

• 폴더 구조, 기존 README/문서, 패키지 매니페스트, 빌드 파일, 예제, 라이선스 파일, Git 상태를 검사합니다.
• .git이 존재하는지, 원격이 설정되어 있는지 확인합니다.
• 원격 생성 또는 푸시 전에 시크릿 위험 파일(.env, 자격 증명, 토큰, 대용량 바이너리, 데이터셋, 개인 노트, 로컬 로그, 시스템별 경로)을 식별합니다.
• 기존 강점, 누락된 오픈소스 필수 요소, 사용자 입력이 필요한 불확실성을 요약합니다.

2. 비코드 추가 계획

허용된 문서 및 메타데이터 작업만 포함하는 간결한 계획을 만듭니다.

• create-readme 스킬을 기반으로 구조, 어조, GitHub Flavored Markdown을 사용하는 README 개선.
• 기본적으로 이중 언어 README: 기본(영문) README가 확정되면 중국어 버전을 README.zh-CN.md로 저장하고 두 파일을 상호 연결합니다. 긴 문서나 용어가 많은 문서의 경우 baoyu-translate 스킬을 사용하여 전역 용어 일관성을 유지합니다.
• 커뮤니티 건강 파일: 기본적으로 MIT 라이선스, 기여 가이드, 행동 강령, 보안 정책, 지원 가이드, 변경 로그, 인용, 거버넌스, 이슈 템플릿, PR 템플릿.
• 저장소 위생: .gitignore, .gitattributes, .editorconfig, 문서 인덱스, 예제 인덱스, 배지, 프로젝트 설명, 토픽, 펀딩/스폰서 메타데이터(해당되는 경우).
• Git/GitHub 설정: Git이 없으면 초기화, 공개 원격이 없으면 생성, 기본 브랜치 설정, 안전 검사 후 문서 전용 변경 사항 푸시.

3. README 개선

README 생성 또는 갱신에는 create-readme 스킬을 사용합니다. README가 간결하고 매력적이며 유용하도록 합니다.

• 명확한 프로젝트 이름, 태그라인, 간단한 가치 제안.
• 진실하고 유지 관리 가능한 경우에만 배지 사용.
• 가능한 경우 검증된 명령어로 빠른 시작 제공.
• 명령어는 저장소 루트에서 복사하여 붙여넣을 수 있어야 하며 현재 사용자의 절대 로컬 경로를 포함하지 않아야 합니다. ./script.sh, $HOME/..., /path/to/..., <repo>/... 예제를 선호합니다.
• 설치, 사용법, 구성, 예제, 프로젝트 구조, 문제 해결, 전용 파일 링크.
• README 내에 LICENSE, CONTRIBUTING, CHANGELOG, SECURITY 내용을 전체 복사하지 말고 해당 파일로 링크합니다.
• 기존 프로젝트별 지식과 예제를 보존합니다.

영문 README.md가 확정된 후 기본적으로 중국어 번역을 생성합니다.

• 영문 README.md는 상단 근처에 언어 전환 라인(예: English | [简体中文](README.zh-CN.md))을 기본적으로 포함해야 합니다. 동일한 실행에서 중국어 파일이 아직 생성 중이더라도 추가합니다. 링크는 워크플로우가 완료될 때 존재할 경로를 가리킵니다.
• README.md에서 중국어 README.zh-CN.md를 생성합니다. 일반적인 README(짧은 산문과 변경되지 않아야 하는 코드/명령어)의 경우 직접 미러를 작성하는 것이 선호됩니다. README가 길거나 용어가 많고 공유 용어집이 필요한 경우에만 baoyu-translate 스킬을 사용합니다.
• 중국어 README.zh-CN.md는 상단에 미러 전환 라인(예: [English](README.md) | 简体中文)을 포함합니다.
• 모든 코드 블록, 명령어, 경로, 링크, 배지, 플레이스홀더는 변경하지 않고 그대로 유지합니다. 산문만 번역합니다.
• 사용자가 명시적으로 거부하는 경우에만 중국어 버전을 건너뜁니다. 프로젝트가 이미 주로 중국어로 작성된 경우 README.md를 중국어 버전으로 처리하고 README.en.md로 번역한 후 각 파일 상단에 해당 전환 라인을 넣습니다.

4. 커뮤니티 파일 추가

프로젝트가 완전하고 신뢰할 수 있게 보이는 데 도움이 되는 경우에만 파일을 추가하거나 업데이트합니다.

• LICENSE: 기존 라이선스가 있으면 사용하고, 없으면 해당되는 경우 감지된 현재 연도와 소유자/프로젝트 이름과 함께 기본적으로 MIT를 추가합니다.
• CONTRIBUTING.md: 개발 설정, 추론 가능한 경우 브랜치/커밋 규칙, 테스트 기대 사항, 이슈/PR 프로세스.
• CODE_OF_CONDUCT.md: 사용자가 다른 정책을 가지고 있지 않은 경우 표준 간결한 기여자 서약 스타일을 사용합니다.
• SECURITY.md: 지원되는 버전, 책임 있는 공개 채널 플레이스홀더, 취약점 보고 기대 사항.
• CHANGELOG.md: Unreleased 및 현재 공개 기준으로 초기화합니다. 릴리스 기록을 임의로 만들지 않습니다.
• SUPPORT.md: 질문, 버그 신고, 기능 요청을 할 수 있는 곳.
• .github/ISSUE_TEMPLATE/* 및 .github/PULL_REQUEST_TEMPLATE.md: 프로젝트에 맞춤화된 실용적인 양식/체크리스트.
• CITATION.cff: 연구/학술/과학 프로젝트 또는 저작권 메타데이터를 사용할 수 있는 경우에만.

5. 저장소 위생

• 감지된 언어/도구를 기반으로 .gitignore를 생성하거나 개선하되, 소스 아티팩트일 가능성이 있는 파일은 제외하지 않습니다.
• 필요한 경우 텍스트 정규화 및 일반적인 바이너리 패턴을 위해 .gitattributes를 추가합니다.
• 저장소 스타일과 일치하는 보수적인 공백 기본값으로 .editorconfig를 추가합니다.
• 빌드/테스트 명령어를 알거나 검증하지 않는 한 CI 워크플로우를 추가하지 않습니다. 추가하는 경우 최소한으로 유지하고 비침습적으로 만듭니다.

6. Git 및 원격 처리

Git이 없는 폴더:

1. 폴더 경로를 확인한 후 대상 폴더에 대한 저장소를 초기화합니다.
2. 이 워크플로우에서 생성되거나 변경된 메타데이터/문서 파일만 스테이징합니다.
3. 게시를 진행할 때 문서 중심의 메시지로 커밋합니다.

원격이 없는 Git 저장소:

1. 가능한 경우 gh 인증에서 GitHub 소유자를, 폴더에서 저장소 이름을 추론합니다. 모호한 경우에만 질문합니다.
2. 원격을 생성하기 전에 gh 인증을 확인합니다.
3. 기본적으로 공개 GitHub 저장소를 생성합니다.
4. origin을 추가하고 기본 브랜치를 설정한 후 스테이징된 변경 사항을 검토하고 시크릿이 포함되지 않았는지 확인한 후 푸시합니다.

프로젝트에 맞게 조정된 권장 GitHub CLI 흐름:

git status --short
git remote -v
gh auth status
gh repo create OWNER/REPO --public --source=. --remote=origin --push

네트워크 명령이 실패하면 다음으로 한 번 재시도합니다.

export {HTTP_PROXY,HTTPS_PROXY,ALL_PROXY,http_proxy,https_proxy,all_proxy}=http://127.0.0.1:7890

7. 품질 검사

최종 확정 전:

• 변경된 Markdown 스니펫을 다시 열어 제목, 링크, 코드 펜스, 복사 가능한 명령어 들여쓰기를 확인합니다.
• README 및 공개 문서에서 /home/, /Users/, 드라이브 문자 경로, 개인 작업공간 이름, 현재 환경에서 복사된 절대 경로를 포함한 로컬 머신 경로를 검색합니다.
• 명시적으로 승인되지 않은 한 소스 코드 파일이 수정되지 않았는지 확인합니다.
• 로컬 파일에 대한 모든 링크가 존재하는 파일을 대상으로 하는지 확인합니다.
• 중국어 README가 생성된 경우 README.zh-CN.md가 존재하고, 언어 전환 링크가 두 파일에서 모두 작동하며, 코드/명령어/경로가 영문 버전과 동일한지 확인합니다.
• 가능한 경우 가벼운 포맷팅 또는 마크다운 린팅을 실행합니다. 사용자가 동의하지 않는 한 이 워크플로우를 위해 무거운 종속성을 설치하지 않습니다.
• git diff --stat를 표시하고 변경된 파일을 요약합니다.
• 원격이 생성된 경우 URL, 가시성, 기본 브랜치, 푸시 여부를 보고합니다.

결정 지점

• 기존 README가 훌륭한 경우: 구조를 유지하고 누락된 섹션을 패치하며 처음부터 다시 작성하지 않습니다.
• 검증된 설치/테스트 명령어가 없는 경우: 명령어를 임의로 만들지 말고 명확하게 표시된 플레이스홀더 또는 "아직 문서화되지 않음" 메모를 포함합니다.
• 라이선스를 알 수 없는 경우: 사용자가 다른 라이선스를 요청하지 않는 한 기본적으로 MIT를 추가합니다.
• 가능한 시크릿 또는 개인 데이터: 원격 생성/푸시를 중단하고 위험한 경로를 보고합니다.
• gh CLI가 없거나 인증되지 않은 경우: 사용자가 실행할 정확한 명령어를 제공하지만, 로컬 문서 폴리싱은 완료하고 안전한 경우 문서 전용 커밋을 준비합니다.
• 모노레포: 패키지 경계가 명확한 경우에만 루트 커뮤니티 파일과 패키지별 README 파일을 생성하거나 업데이트합니다.

완료 요약

다음과 같이 종료합니다.

• 추가/업데이트된 파일.
• 의도적으로 건드리지 않은 항목, 특히 소스 코드.
• 수행된 검증.
• 원격 저장소 상태(해당되는 경우).
• CI 활성화, 예제 추가, 첫 번째 릴리스 준비, 프로젝트 토픽 생성 등 제안된 다음 단계.