Contribute(기여하기)

티켓 제출하기(Submitting tickets)

Prototype 핵심 팀은 이슈 트래커로서 Lighthouse를 이용한다. 티켓을 오픈하기 위해서는 먼저 등록을 해야 하지만 잠깐이 소요될 뿐이다(그리고 무료이다).

타이틀은 자기 묘사적이고 간결함을 유지하도록 노력하되 자신의 생각은 자세한 내용을 위한 필드에서 작성하라. 텍스트에 자바스크립트 코드 단편을 포함시킬 필요가 있다면, 다음처럼 적당히 마크업을 입혀라:

This line opens a popup every time, which scares me!

@@@ javascript
var scary = 'BOO!'
window.alert(scary)
@@@

Can Prototype be used to make this less scary? Thank you.

패치를 첨부하기 위해 이 기능을 사용하지는 않았으면 하는데, 패치는 티켓의 첨부파일로서 업로드하라.

코드 작성하기(Writing Code)

패치와 테스트에 기여하기 위해서 대부분의 경우에는 다음 사항이 필요하다:

1. Prototype 최신 버전(원칙적으로는 Git 클라이언트를 사용하지만 tarball 또한 사용가능하다)
2. 자신이 애용하는 코드 편집기
3. 자신의 운영체제에서 동작하는 모든 종류의 최신 브라우저(물론 테스트를 위해서)
4. Ruby와 Ruby의 Rake 라이브러리 최신 버전. Ruby는 MacOS X에서는 기본설치되어 제공되지만 Windows 사용자는 Ruby 원클릭 인스톨러을 이용할 필요가 있다.
5. Rake는 통합된 자바스크립트 파일을 생성하고(build) 지원되는 브라우저에서 프로젝트에서 제공하는 테스트 자동화 패키지(the automated test suite)를 실행하는 데 사용된다.

저장소로부터 프로젝트를 복제하는 것으로부터 시작하라.

git clone git://github.com/sstephenson/prototype.git

이 명령은 prototype이라는 이름의 새 디렉토리를 생성할 것이다. 여기서 가장 중요한 디렉토리는 코드가 존재하는 src/, 모든 단위 테스트뿐만 아니라 테스트 프레임워크를 제공하는 test/이다.

프로젝트의 루트 디렉토리에서 다음을 입력하라.

rake dist

이것은 Rake 태스크가 src/의 모든 파일을 dist/prototype.js라는 단일 파일로 병합한다는 것을 미리 정의한다. 단위 테스트는 이 파일을 이용한다. 단위 테스트가 어떻게 이뤄지는지 알고 싶다면 test/unit/의 HTML 파일 중 아무거나 브라우저에서 열어보라. 단위 테스트가 자동적으로 실행되면, 잠시 후에 녹색 라인(green-colored rows)이 부산스럽게 움직이는 것(flurry)을 보게 될 것이다.

지원되는 브라우저를 이용하고 있다면 대개 테스트 실패는 일어나지 않는다.

테스트 실패의 경우를 살펴보기 위해 한 번 고의적으로 에러를 발생시켜 보자. src/array.js를 열어 상단에서 first라는 이름의 메소드를 찾는다.

first: function() {
	return this[0];
},

그냥 재미삼아 리턴 라인을 ("foo"나 "hello!" 같은) 문자열을 되돌려주도록 변경하고 저장하라. rake dist 명령을 넘겨주어 prototype.js 파일을 다시 생성하고 브라우저에서 test/unit/array.html을 열라. 2라인짜리 메세지를 포함하는 단일 테스트가 적색으로 되어 있을 것이다. 축하한다, 이제 막 망가진 Prototype을 만들었다! ;)

여기서부터는 혼자 처리해야 하는 부분으로, src/ 안의 소스 파일에 미친 척하고 임의의 메소드를 추가한다. 완료했으면 Lighthouse에 새로운 티켓을 생성하라. 몇 번째 라인을 변경하라거나, 소스를 붙여넣기 하지말고 생성한 티켓에 직접 패치(diff 파일로 불리기도 한다)를 첨부하라. Git를 사용하고 있다면 다음처럼 패치를 생성할 수 있다.

# first be sure to commit your changes locally
git commit -a -m "fixed a bug regarding the DOM"

# make the patch file(s)
git format-patch origin

이 명령은 로컬에서 작업한 각 커밋을 (숫자로 시작하는) 하나의 패치 파일로 만들어 준다. 잘 했다. 티켓에 그 파일을 업로드하라.(Git를 사용하지 않고 diff를 생성할 수도 있다. 이는 플랫폼에 종속적이기 때문에 다양한 방법이 존재한다. 구글은 우리의 벗이다.)

뿐만 아니라 GitHub 사용자라면 이 방법 대신에 프로젝트를 분기하여 자신의 변경점을 반영한 후, GitHub의 인터페이스를 통해 풀 요청(pull request)을 샘(sstephenson)에게 보낼 수 있다.

코딩 스타일에는 몇 가지 가이드라인이 있다:

• 2 스페이스를 쓸 것. 탭은 금지.
• 변수명을 명확하고 묘사적으로 유지할 것.
• 루프(loop)와 같은 일반 구조에서 부하가 적게 걸리는 방법(low-hanging performance fruit)을 강구하는 것을 잊지 말 것.
• 코드에 이미 존재하는 관례를 따를 것.

테스트의 중요성(The importance of testing)

단위 테스트(unit testing)는 새로 추가된 기능이 기존의 기능을 저해하지 않는다는 점을 보증해 준다. 또한 라이브러리가 지원대상에 포함되는 모든 브라우저에서 일관되게 동작한다는 점도 보증한다. 패치를 제출하려 한다면 테스트 또한 반드시 제출하라. 제출된 테스트를 통해 제출자의 진정한 의도가 파악되어야 제출된 코드가 안전하게 코어(core)에 반영될 수 있다. 테스트와 함께 제출되지 않은 패치가 채택되는 경우는 거의 없는데, (누군가가 나서서 테스트를 작성하기를 기다리는 것보다) 스스로 테스트를 작성한다면 제출한 패치가 수용될 가능성이 비약적으로 증가한다.

패치가 새로운 기능을 포함하고 있다면 새 기능을 시연할 수 있는 테스트 케이스를 포함하고 있어야 한다.

버그 수정을 포함하고 있는 패치라면 무엇이 패치되었는지를 문서화하기 위한 테스트 케이스를 포함해야 한다. 이런 이유로, 해당 패치가 적용되지 않은 상태에서 테스트 케이스는 실패해야 하며, 적용된 후에는 성공해야 한다.

변경점을 테스트하기 전에 먼저 사용중인 Prototype이 최신 버전인지 확인해보자.

git pull

Git는 마지막으로 소스를 받은 이후에 생긴 변경을 받아올 것이다. 그 후 run dist를 실행하면 자신이 /src 안에 만들었던 변경점이 배포가능한(distributable) 상태로 생성될 것이다.

마지막으로 테스트를 실행해보자.

run test

이 명령은 설치되어 있는 모든 브라우저(당연히 플랫폼 의존적이다), 즉 사파리, 파이어폭스, 인터넷 익스플로러, 오페라, 컨쿼러(Konqueror)에 걸쳐 Prototype의 전체 테스트(모든 단위 테스트)를 실행한다. 테스트는 한 페이지씩 진행되며 터미널에 결과를 반환한다.

만약 테스트 중 실패한 것이 있다면, 원인을 이해하고 수정하여 다시 테스트를 실행할 필요가 있을 것이다. 다음 과 같은 명령방식으로 전체 테스트를 재실행하지 않고 특정 브라우저, 특정 테스트 그룹으로 테스트 작업(testing task)을 제한할 수 있다.

rake test BROWSERS=firefox TESTS=ajax,string

주의: 대부분의 테스트는 브라우저 상에서 해당 테스트에 상응하는 HTML 파일을 여는 것만으로 rake 없이 실행될 수 있다. 그러나 몇몇 테스트(특히 ajax.js)는 클라이언트-서버 통신(client-server communication)에 의존적이다. Rake는 로컬 웹 서버를 생성하여 테스트를 실행한다.

모든 단위 테스팅 라이브러리는 Ruby의 Test::Unit과의 유사점을 내포하고 있어 넓은 범주의 다양한 타입의 검증(assertions)을 허용한다. 여기에 이 부분에 대한 프리젠테이션이 있다.

일반적 실수(Common mistakes)

다음과 같은 경우를 많이 볼 수 있었다.

• 매우 특정 어플리케이션 제한적인 요청/패치: 프레임워크는 상상할 수 있는(ever imagined) 모든 시나리오를 커버하지 않는다. 보다 일반적으로 사용되는 특성(stuff)에 집중하려 노력하라.
• 문제를 재현하는 방법을 설명하지 않는 버그 리포트(버그의 상세한 재현절차와 어떤 브라우저에서 발생하는지 알려달라!)
• 사실상 단순히 git pull이나 rake dist를 잊은 데서 발생하는 오류에 대해 불평하는 티켓.
• 실행 속도를 고려하지 않고 재작된 패치: 그다지 중요하지 않은 기능을 추가하기 위해 중요 코드를 느리게 만들지 말아달라.
• 크로스 브라우저가 아닌 패치: 적어도 파이어폭스와 이외 1개의 최소 2개 브라우저는 테스트를 하라.
• 중복요청 또는 중복 패치: 누군가 자신보다 먼저 동일한 작업을 하지 않았는지 Lighthouse를 검색하라.

Prototype.js은 압축이 잘 되지 않는다! 이 문제를 수정한 패치를 올려도 되는가?(Prototype.js doesn't compress well! Can I submit a patch to fix that?)

Prototype 코드에는 문제가 없으며, 사용자가 사용중인 JS 압축 프로그램에 문제가 있다. 자신의 로컬 복사본을 자신의 취향대로 변경해 원하는 대로 압축해 사용할 수는 있으나, Prototype 자체에서 이 부분을 지원하지는 않을 것이다. 우리는 사용자 웹 서버 상의 gzip 설정이라는 좋은 기능을 추천하는데, Prototype은 gzip을 통해 30kB 보다 적은 사이즈로 압축된다.

gzip을 사용할 수 없는 상황이라면, 몇몇 사람들이 관리중인 Prototype과 script.aculo.us의 비공식 압축 버전이 존재한다. 구글이 어디로 가야하는지 알려줄 것이다.

우리는 또한 단지 JSLint나 파이어폭스의 strict 검사 모드에서 발생하는 경고로 인해 코드를 변경한 패치를 수용하지 않는다. 코드 검사기(code linters)는 문제의 소지가 있는 관용구문(idioms)과 구조를 검사하는데, 결과적으로 잘못된 검사결과(flase positives)를 양산한다.

API 문서의 개선(API documentation enhancements)

우리가 놓친 부분이 있다고 생각한다면 API 문서에 기여하는 것을 환영한다. 문서는 마크다운(Markdown) 포맷으로 작성된다. 원한다면 템플릿으로써 Element#getElementsBySelector 메소드의 문서화 소스를 이용할 수 있을 것이다.

## getElementsBySelector

<pre><code class="ebnf">
	getElementsBySelector(element, selector...) -> [HTMLElement...]
</code></pre>

Takes an arbitrary number of CSS selectors (strings) and returns a
document-order array of [extended](/api/element/extend) children of `element`
that match any of them.

---------------------------------------------------------------------

This method is very similar to [$$()](/api/utility/dollar-dollar) but can be
used within the context of one element, rather than the whole document. The
supported CSS syntax is identical, so please refer to the
[`$$()` docs](/api/utility/dollar-dollar) for details.

### Examples

<pre><code class="javascript">
$('apples').getElementsBySelector('[title="yummy!"]');
// -> [h3, li#golden-delicious, li#mutsu]

$('apples').getElementsBySelector( 'p#saying', 'li[title="yummy!"]');
// -> [h3, li#golden-delicious, li#mutsu,  p#saying]

$('apples').getElementsBySelector('[title="disgusting!"]');
// -> []
</code></pre>

### Tip

`Element#getElementsBySelector` can be used as a pleasant alternative to
`getElementsByTagName`.

Git

리누스 토르발스(Linus Torvalds)가 Linux kernel 개발을 위해 만든 분산형 버전관리 시스템(Distributed Version Control Systems). 최근 Ruby on Rails가 Git 기반으로 옮겨가면서 주목을 받기 시작했다. Git이라는 명칭은 멍청하고 불쾌한 사람을 지칭하는 영국 영어의 속어에서 따온 것으로, 자신의 프로젝트에는 자신과 관련된 명칭을 붙인다는 토르발스의 지론에 따라 정해진 명칭이라고 한다.

풀 요청(pull request)

누군가에게 기별하여(poke someone), 그가 원하는 코드를 자신이 가지고 있다는 것을 알리는 것.

샘(Sam Stephenson)

Prototype의 창시자.