GitHub 초보자 가이드

GitHub 초보자 가이드은(는) 무엇을 하나요?

비공식 커뮤니티 스킬입니다. 사실은 GitHub 공식 문서에서 확인했습니다(V). 법적 조언이 아닙니다.

스타일 (엄격히 따를 것)

• 사용자가 아무것도 모르고 Git을 배울 의사가 없다고 가정합니다. 결과만 원한다고 생각합니다.
• 한 번에 하나의 단계만 알려줍니다. 사용자가 보게 될 정확한 버튼이나 링크 텍스트를 말해줍니다. 사용자가 다음 단계를 말하기 전까지 기다리세요.
• 한 줄 요약으로 시작하세요. 세부 사항은 요청받았을 때만 알려줍니다.
• 사용자가 스크린샷을 보내면, 읽고 현재 위치를 알려준 후 다음 지시를 내립니다.
• 만약 당신(어시스턴트)이 저장소 접근 권한으로 직접 단계를 수행할 수 있다면, 직접 하겠다고 제안하세요. 적절한 도구나 로그인 절차를 통해 접근 권한을 요청하세요. 사용자에게 비밀번호나 접근 토큰을 채팅에 붙여넣도록 요청하지 마세요.

1. 저장소 생성하기

1. github.com 오른쪽 상단의 +를 클릭한 후, New repository를 클릭하세요.
2. 이름: 짧게, 소문자, 하이픈 사용 (예: my-plugin).
3. Public(누구나 볼 수 있음) 또는 Private을 선택하세요.
4. Add a README를 체크하세요. 드롭다운에서 라이선스를 선택하세요 (5장 참조).
5. Create repository를 클릭하세요.

빈 저장소는 "Quick setup" 페이지와 명령줄 상자를 보여줍니다. 초보자는 그 모든 것을 무시하고 "uploading an existing file" 링크를 사용하면 됩니다.

2. 저장소에 파일 넣기 (웹, Git 없이)

저장소 페이지에서: Add file, 그 다음 Upload files를 클릭하세요. 그런 다음 파일을 드래그하거나 "choose your files"를 클릭하세요.

제한 사항 (V: GitHub 문서, Adding a file to a repository):

• 브라우저에서 업로드할 때 파일당 25 MiB.
• 업로드당 최대 100개 파일.
• 더 큰 파일(최대 100 MiB)은 명령줄이 필요하며, 100 MiB를 초과하는 파일은 Git Large File Storage가 필요합니다.
• 보호된 브랜치는 웹 업로드를 통해 편집할 수 없습니다.
• Push protection은 토큰과 같은 지원되는 비밀을 포함하는 파일을 차단할 수 있습니다.

폴더: 문서에 따르면 파일이나 폴더를 드래그할 수 있습니다. 사용자의 브라우저가 폴더를 받아들이지 않으면, 다음 중 하나를 대신 사용하세요:

• 웹 편집기에서 폴더 만들기: Add file, Create new file, 이름 상자에 폴더이름/파일이름.md 입력 (슬래시를 입력하면 폴더가 생성됨), 내용 추가, 그 다음 커밋. 현재 UI에서 동작을 확인하세요.
• 폴더의 압축을 풀고 파일을 폴더 경로를 유지한 채 배치로 업로드하거나, GitHub Desktop을 사용하세요.
• 어시스턴트가 저장소 접근 권한이 있다면 파일을 푸시하게 하세요.

Zip 파일은 단일 파일로 저장됩니다. GitHub은 압축을 풀지 않습니다. 압축을 푼 내용을 업로드하세요.

커밋 메시지(짧게, 무엇이 변경되었는지)와 Commit changes 버튼으로 마무리하세요.

결과 확인: 저장소 페이지를 열고 파일 목록을 의도한 것과 비교하세요. 흔한 실수: 파일이 폴더 대신 루트에 놓이는 경우.

3. 다운로드 가능한 릴리스 (사용자가 다운로드할 것)

릴리스는 Git 태그를 기반으로 한 라벨이 붙은 다운로드 페이지입니다 (V: GitHub 문서, About releases).

1. 저장소 페이지에서 Releases(오른쪽)를 클릭한 후, Draft a new release를 클릭하세요.
2. v1.0.0과 같은 태그를 선택하세요 (새 태그를 입력한 후 Create new tag).
3. 제목과 노트: 무엇인지, 설치 방법(세 단계), 변경 사항.
4. 파일을 자산 상자로 드래그하세요. 초보자에게 친숙한 릴리스에는 운영 체제별 빌드된 설치 프로그램이나 파일, 짧은 매뉴얼, 설치 지침이 포함되어야 하며, 베어 파일이나 소스 코드만 있으면 안 됩니다.
5. Publish release를 클릭하세요.

제한 사항 (V): 각 파일은 2 GiB 미만, 릴리스당 최대 1000개 자산, 전체 크기나 대역폭 제한 없음.

릴리스 노트 템플릿:

• 무엇인지 (한 줄)
• 다운로드: 시스템 선택 (Windows, macOS, Linux)
• 세 단계로 설치
• 각 파일에 대한 체크섬 (SHA-256)
• 알려진 문제

4. 라이선스 및 README 기본 사항

• 라이선스가 없는 저장소는 오픈 소스가 아닙니다. 다른 사람이 재사용할 권리가 없습니다. 신중하게 선택하세요.
• MIT: 매우 허용적이고 짧습니다. AGPL-3.0 또는 GPL: 카피레프트(share-alike). JUCE의 오픈 소스 옵션 아래 구축된 프로젝트는 AGPLv3의 적용을 받습니다 (V: JUCE 포럼, 스태프). 따라서 선택하기 전에 현재 JUCE 라이선스를 확인하세요.
• 귀하가 권리를 소유하지 않은 공급업체 파일(매뉴얼, 공장 프리셋, 로고, 바이너리)을 게시하지 마세요. 대신 링크하세요.
• README는 다음 질문에 답해야 합니다: 무엇인지, 설치 방법, 사용 방법, 라이선스, 문제 보고 방법.

5. 개인 정보를 지키기 (가장 중요)

첫 번째 공개 푸시 전에, 모든 파일과 커밋 신원에서 다음을 검색하세요: 실명, 개인 이메일, 전화번호, 주소, 고용주, 토큰, 비밀번호, 사용자 이름이 포함된 로컬 경로.

커밋 신원:

• GitHub noreply 주소를 사용하세요. Settings, Emails에서 "Keep my email addresses private"를 체크한 상태입니다. 형식: <숫자 ID>+<사용자이름>@users.noreply.github.com.
• 커밋 전에 설정하세요: git config user.name "<사용자이름>" and git config user.email "<ID>+<사용자이름>@users.noreply.github.com". 푸시 전에 git log --format='%an <%ae>'로 확인하세요.
• 어시스턴트가 사용자를 대신해 커밋할 때, 이 신원을 사용해야 하며 절대 사용자의 실제 이메일을 사용하지 마세요.

만약 개인 데이터가 이미 공개되었다면 (V: GitHub 문서, Removing sensitive data from a repository):

1. 자격 증명인 경우, 먼저 취소하거나 순환시키세요. 그것만으로 충분할 수 있습니다.
2. 로컬에서 git-filter-repo를 사용하여 기록을 재작성하세요 (버전 2.47 이상에서 --sensitive-data-removal 지원). --invert-paths --path로 파일을 제거하거나 --replace-text로 텍스트를 대체하세요.
3. Force-push하여 GitHub의 저장소를 덮어쓰세요.
4. GitHub 지원팀에 연락하여 캐시된 보기와 풀 리퀘스트 참조를 제거하세요. 저장소 이름, 영향을 받은 PR 수 및 도구의 출력에서 첫 번째 변경된 커밋을 알려주세요.
5. 포크는 데이터를 유지합니다. 포크 소유자에게 제거를 요청하세요. 협업자는 병합하지 말고 리베이스하세요.
6. 문서의 경고: 다른 사람의 클론은 데이터를 유지하며, 기록 재작성은 제거된 내용을 드러낼 수 있습니다. 데이터가 이미 보여졌다고 가정하세요.

최근 커밋을 수정하는 것은 브랜치 끝에만 충분합니다. 이전 커밋은 GitHub이 정리할 때까지 직접 링크로 여전히 접근 가능하므로 4단계가 여전히 적용됩니다.

5b. 공개할 내용 선택하기

• 연구 노트, 캡처된 장치 데이터, 개인 메모 및 채팅 기록은 사용자가 명시하지 않는 한 공개 저장소에 속하지 않습니다.
• 공개용으로 작성되지 않은 것을 게시하기 전에 물어보세요.

6. 일상적인 작업 (한 번에 하나씩)

• 웹에서 파일 편집: 파일 열기, 연필 아이콘, 변경, Commit changes.
• 파일 삭제: 파일 열기, 세 점, Delete file, 커밋.
• 이름 바꾸기 또는 이동: 파일명 상자 편집, 새 경로 입력, 커밋.
• 프로필에 저장소 고정: 프로필 페이지, Customize your pins.
• 프로젝트 웹 페이지 활성화 (GitHub Pages): Settings, Pages, 브랜치와 폴더 선택. 현재 UI를 확인하세요.
• 문제 보고 또는 추적: Issues 탭. 버그 보고용 이슈 템플릿 제공.

7. 실패 시 처리

• 업로드 거부됨: 파일 크기(웹 25 MiB 제한), 파일 수(100), 보호된 브랜치를 확인하세요.
• 폴더 누락: 파일이 평평하게 업로드됨. Create new file로 경로를 재생성하거나 재업로드하세요.
• Push가 비밀 경고로 거부됨: 비밀을 제거하고, 순환시킨 후 다시 시도하세요.
• 보안 프롬프트를 비활성화하라고 절대 제안하지 마세요.

출처

• GitHub 문서, Adding a file to a repository: https://docs.github.com/en/repositories/working-with-files/managing-files/adding-a-file-to-a-repository
• GitHub 문서, About releases: https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases
• GitHub 문서, Removing sensitive data from a repository: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository