한글번역 프로젝트 참여방법 #1.git사용하기


#1

#업데이트! 오픈프레임웍스 한글그룹저장소를 만들었습니다.
ofSite 저장소
ofBook 저장소
이 두곳에서 작업해주시면 됩니다. 업로드 권한을 얻으시려면 이곳에 github 계정명을 댓글로 달아주세요 :slight_smile:

번역 프로젝트 참여하기

오픈프레임웍스 한글번역 프로젝트 참여 방법에 대해 정리합니다.

간단한 정리를 우선 하자면 다음과 같습니다.

  1. 원본 저장소 fork
  2. 자신의 저장소 (fork된 저장소)를 로컬에 clone
  3. 번역작업 (.ko.md파일 생성, 편집)
  4. git add, git commit
  5. git push origin master 자신의 저장소에 푸시
  6. 원본 저장소로 pull-request

markdown 포맷

오픈프레임웍스 웹사이트/ofBook은 마크다운 포맷으로 작성됩니다.
번역에 참여하실분들은 따라서 markdown문법에 익숙해지셔야 합니다.
다만, 처음부터 문서를 작성하는 것이 아니라, 원래 있는 영문문서를 번역하는 것이므로, 완벽하게 숙지하지 않아도 참여하실 수 있습니다.

github

오픈프레임웍스 사이트와 ofBook은 모두 github에서 진행되고 있습니다.
github은 버전관리도구인 git을 네트워크로 관리하여 여러 사람이 공동프로젝트를 진행할수 있도록 도와주는 플랫폼입니다. http://github.com/에 접속하셔서 가입하여 계정을 만들어주셔야 합니다.

github의 워크플로우

git의 세부 명령어를 살펴보기 전에 github에서의 워크플로우에 대해서 간략하게 설명드리겠습니다.

일단 깃허브는 누구든지 자신의 저장소를 만들어 운영할 수 있으며, 특정한 설정 없이는 업로드 권한은 저장소를 만든 오너에게만 있습니다.

자 유저 A가 만들어 관리하고있는 이 원본 저장소를 repo_A이라고 해봅시다.
github에서는 저장소를 만들면 **http://github.com/<%사용자아이디%>/<%프로젝트명%>/**의 주소를 갖습니다.

오픈프레임웍스의 ofSite 저장소를 살펴볼까요 ?
주소는 http://github.com/openframeworks/ofSite/ 가 됩니다.
즉 openframeworks라는 사용자의 ofSite 프로젝트인 것이죠.

앞서 말씀드렸다시피, 권한설정을 별도로 해주지 않으면, 이 프로젝트 저장소에 업로드할 수 있는 권한은 openframeworks에 있습니다. (정확히는 openframeworks 그룹? 정도가 되겠습니다)

자 그렇다면, 프로젝트A에 참여하고 싶다면 어떻게 해야할까요 ?
우선, 원본 저장소 repo_A를 자신의 저장소로 fork(복제)해야합니다.
자신의 프로젝트가 아닐 경우 업로드 권한이 없기 때문에, 일단 원본 저장소를 자신의 저장소로 복제하여 자신의 저장소에서 작업을 하는 것입니다.

fork를 할려면, 참여하고싶은 프로젝트의 페이지에서 우측상단의 fork버튼을 누르면 됩니다. 저장소 메인페이지의 우측 상단에 있습니다. fork하는것은 git 명령어와 아무 상관이 없고, github사이트에서 해주셔야 합니다.

fork를 한 뒤에는, 같은 프로젝트명으로 자신의 계정하에 프로젝트가 생성됩니다. 제 계정의 경우라면 주소는 http://github.com/icq4ever/ofSite/(http://github.com/icq4ever/ofSite) 가 됩니다.

자신의 저장소(원본 저장소의 fork본)를 로컬로 복제하기

터미널에서 원하는 디렉토리에 저장소를 복제합니다.
아래의 예제는 /home/git/ofSite에 저장소가 저장됩니다. (이동할 디렉토리는 따라서 /home/git이며, 그 뒤에 clone하면 됩니다.)
깃의 주소는 자신의 깃헙 프로젝트 페이지에서 확인할 수 있습니다.
http://github.com/<%계정명&>/<%프로젝트명%>의 형식입니다.

$ cd /home/git
$ git clone http://github.com/icq4ever/ofSite
# 저장소가 클론됨

clone을 하게 되면, github상의 원격저장소는 디폴트로 origin이라는 이름으로 등록됩니다.
remote를 확인하는 명령어는 git remote -v 입니다.

$ git remote -v
origin	http://github.com/icq4ever/ofSite (fetch)
origin	http://github.com/icq4ever/ofSite (push)

원격 저장소(github의 저장소)와 로컬 저장소의 관계를 간략히 표현하자면 아래와 같습니다

				복사본 원격 저장소
github.com 		[icq4ever/ofSite]

                ▲ PUSH (git push)
                ▼ FETCH (git fetch)

remote -r		origin

작업하기전 원본 저장소의 업데이트 내역을 가져와 합치기

자신의 저장소는 사실 원본의 fork된 저장소입니다.
만약 원본의 저장소가 업데이트 되었다면, 저장소에서 작업하기 전에 업데이트 내역을 반영해주어야 합니다.

원본의 업데이트를 반영하지 않고 작업을 하다가 원본의 작업내용과 자신의 작업내용이 겹치는 경우가 발생할 수 있습니다. 이런 경우 push나 merge(또는 pull)를 할때 충돌이 발생할 수가 있는데, 이 충돌(conflict)을 해결하는것은 다소 까다로운 편이므로 미리미리 충돌을 예방해주는것이 좋습니다.

원본 저장소의 업데이트내역을 로컬에 반영하기 위해서는, git remote add 명렁어를 통해서 remote에 원본 저장소를 추가해줄 필요가 있습니다.
git remote add <%remote명 %> <%원본 원격저장소 주소%>
보통 원본 원격저장소의 remote명은 upstream이라고 지정합니다.

$ git remote add upstream http://github.com/openframeworks/ofSite
$ git remote -v
origin	http://github.com/icq4ever/ofSite (fetch)
origin	http://github.com/icq4ever/ofSite (push)
upstream	http://github.com/openframeworks/ofSite (fetch)
upstream	http://github.com/openframeworks/ofSite (push)

이제부터는 원본저장소가 아닌 , 자신의 fork된 저장소에서 작업을 진행하시면 됩니다.

			원본 원격 저장소 									복사본 원격 저장소
github.com 	[openframeworks/ofSite]   <--*pull request--	[icq4ever/ofSite]
			푸시/풀 권한 없음 									▲ PUSH
			(오류)											▼ PULL

remote -r	upstream										origin

* pull request는 github에서 진행할 수 있음

git fetch, git merge

$ git fetch upstream
remote: Counting objects: 44, done.
remote: Compressing objects: 100% (44/44), done.
remote: Total 44 (delta 19), reused 0 (delta 0), pack-reused 0
Unpacking objects: 100% (44/44), done.
From http://github.com/openframeworks/ofSite
   92957b0..373022b  master     -> upstream/master

$ git merge upstream/master
Merge made by the 'recursive' strategy.
 conf.py                                       |  2 +-
 content/setup/raspberrypi/Raspberry-Pi-SMB.md | 32 ++++++++++++++++-
 utils/collect_stats.sh                        | 98 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 utils/install_web_server.sh                   | 29 ++++++++++++++++
 4 files changed, 159 insertions(+), 2 deletions(-)
 create mode 100755 utils/collect_stats.sh
icq4ever@icq4ever-x201-linux:~/Documents/git/ofSite$ git status
On branch master
Your branch is ahead of 'origin/master' by 15 commits.
  (use "git push" to publish your local commits)

nothing to commit, working directory clean

번역하기

이제 원본인 remote 원격 저장소의 업데이트 내역이 반영되었으므로, 번역작업을 시작하시면 됩니다.

번역할 한글 문서 생성

한글문서 번역본을 만들기 위해서는 한글번역이 될 파일을 먼저 만들어야 합니다.
모든 문서는 markdown으로 되어있으며, 파일 확장자는 md 입니다.
가령 예를들어 msys2셋업 문서의 경우 위치와 파일명은 아래와 같습니다.

/<%저장소 폴더%>/content/setup/msys2.ko.md

이 문서의 경우 한글번역이 되어있지 않습니다. 한글번역을 위해 이 파일을 복제하여 파일명을 아래와 같이 지정해줍니다

  • msys2.**ko.**md

터미널에서라면 아래와 같은 명령어를 사용하면 됩니다.

$ cd /home/git/content/setup/
$ cp msys2.md msys2.ko.md

msys2.ko.md파일을 가지고 번역작업을 하시면 됩니다.

번역작업후, add, commit

이제 파일을 저장하면, git status에 변화가 생깁니다.

$ git status
On branch master
Your branch is ahead of 'origin/master' by 2 commits.
  (use "git push" to publish your local commits)

Untracked files:
  (use "git add <file>..." to include in what will be committed)

	content/setup/msys2.ko.md

nothing added to commit but untracked files present (use "git add" to track)

이는 새로 생긴 msys2.ko.md 이 git상에 추적되지 않기 떄문입니다.

이 파일을 원격저장소에 업로드하기 위해서는 우선 이 파일을 git의 stage(index)에 추가하고 add된 파일의 변경 내역을 커밋해줘야합니다.
add와 commit을 해주지 않으면, 깃허브에 업로드되지 않습니다.
commit을 할때에는, 무슨 작업을 했는지 메시지를 작성해줍니다.
커밋 메시지는 ofSite에 반영될 것이므로 영문으로 작성하시는것이 좋습니다.

$ git add content/setup/msys2.ko.md
$ git commit -m "added korean translation of msys2"
[master 6720aa5] added korean translation msys2
 1 file changed, 113 insertions(+)
 create mode 100644 content/setup/msys2.ko.md

자신의 깃허브에 push 하기

커밋을 하면, push가 가능합니다. (add를 했더라도, commit을 하지 않으면 push할 수 없습니다. 다시말해 push할때에는 commit된 파일만 push 됩니다.)

git push의 형식은 다음과 같습니다

git push <%원격 저장소 이름&> <%로컬브랜치명%>

자신의 깃허브 저장소는 origin이고, 브랜치를 별도로 만들지 않았다면, mater가 됩니다.
아래와 같이 명령어를 입력하면 github의 아이디와 비번을 묻습니다. 입력하면 작업한 내역이 깃헙의 자신의 저장소에 반영됩니다.

$ git push origin master
Username for 'https://github.com': icq4ever
Password for 'https://icq4ever@github.com': 
Counting objects: 93, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (63/63), done.
Writing objects: 100% (63/63), 12.75 KiB | 0 bytes/s, done.
Total 63 (delta 35), reused 0 (delta 0)
To http://github.com/icq4ever/ofSite
   f864e72..2d63084  master -> master
$ _

깃헙의 저장소에 가보면 업데이트 내역이 반영되어있음을 확인할 수 있습니다.

자신의 작업한 내용을 원본 저장소에 합치도록 pull-request 요청하기

마지막으로 남은것은 자신의 저장소에서 작업한 내역을 원본 저장소에 합치도록 요청하는 것입니다.
이를 github에서는 pull-request라고 합니다.(종종 줄여서 PR이라도고 합니다)

pull request는 콘솔에서 하는게 아니라 깃헙에서 합니다.
업데이트 후 자신의 저장소로 가시면 new pull request 버튼이 있습니다.

이 버튼을 클릭하면, 원본 저장소의 내용과 자신의 저장소에 반영된 업데이트 내역을 비교하는 Comparing changes페이지가 열립니다. 여기서 어떤 내용이 변경되었는지를 확인할 수 있습니다.

상단에 보시면 왼쪽에 원본 저장소와 브랜치, 우측에 자신의 저장소와 브랜치가 있습니다. openframeworks/ofSite의 master와 icq4ever/ofSite의 master를 비교하고 있는것이죠.

충돌이 없다면, Able to merge가 보이실겁니다.
이제 여기서 Create pull request를 눌러 pull-request를 생성합니다.

pull-request의 제목과 내용을 작성할 수 있습니다.
여기에 작성된 내용은 원본 저장소(openframeworks/ofSite)에 나타나게 되며, 원본 저장소의 업로드 권한이 있는 사용자가 이 내역들을 검토하고 merge할 수 있습니다. 제목에는 간단한 변경내역, 내용에는 상세내역이나 의견을 게시하면 됩니다.


오픈프레임웍스 한글번역 참여하는 방법
#2

장문의 정성글 잘 읽었습니다.
한가지 질문같은 제안이 있습니다.

1.
저 같은 경우 (Github desktop) 을 이용합니다. 제 생각에는 깃헙 계정 만들고, 깃헙데스크탑을 이용하면, 1번 단계 부터 5번 단계는 편리한 GUI 로 가능 하리라 보는데 어떠신지요.

2.
혹은 사이트에서 바로 포크(Fork) 하여 자신의 저장소로 복사본을 만든 다음 (…).ko.md 를 만들어 웹브라우져를 통하여 번역을 붙이는것은 어떠 할까요?

3.
OF 코리아 번역 전용 깃헙 계정을 만들어 참여하실 분들에게 권한을 풀어, 위의 2가지 방법을 이용 하는것은 어떠 할지요?

아무래도 당면 과제는 영문을 한글로 전환 하는 노동력이 우선적으로 집중 되어야 하는데, 저 같은 초보자들에게는 직접 콘솔에 명령어를 타이핑 하여 사용 하는것이 다소 무리가 있습니다. 포럼 분들중 영어능력자 임에도 불구 하고 깃헙 사용법이 어려워 참여율이 낮아질까 다소 우려가 되어 덧 붙입니다.

( 아… 그리고 저는 영어영어 열매를 못먹었습니다 ㅜㅜ. 앞으로 열심히 찾아 먹도록 하겠습니다. )


#3

의견 감사합니다.

  1. 깃헙 데스크탑은 제가 사용해본적이 없어서 튜토리얼 작성을 못했습니다. 당연히 GUI를 사용하는게 훨씬 간편하겠죠!

  2. 브라우저에서 작성하는것도 상관없습니다. 이부분에 대해서는 별도 튜토리얼을 작성해보겠습니다.

  3. 오… 그룹계정(Organization)이 유료인줄 알고 있었는데 무료 플랜이 있군요! 좋은 아이디어입니다! 이방법으로 진행해보겠습니다.