Ruby on Rails에 기여하기

1 이슈 보고하기

Ruby on Rails는 이슈(주로 버그와 새로운 코드의 기여)를 추적하기 위해 GitHub Issue Tracking을 사용합니다. Ruby on Rails에서 버그를 발견했다면, 여기서 시작하면 됩니다. 이슈를 제출하고, 이슈에 댓글을 달거나, pull request를 생성하려면 (무료) GitHub 계정을 만들어야 합니다.

참고: 가장 최근에 릴리스된 Ruby on Rails 버전의 버그가 가장 많은 관심을 받을 것입니다. 또한 Rails 코어 팀은 edge Rails (현재 개발 중인 Rails 버전의 코드)를 테스트하는 데 시간을 할애할 수 있는 사람들의 피드백에 항상 관심이 있습니다. 이 가이드의 뒷부분에서 테스트를 위한 edge Rails를 얻는 방법을 알아볼 것입니다. 지원되는 버전에 대한 정보는 maintenance policy를 참조하세요. 보안 이슈는 절대로 GitHub 이슈 트래커에 보고하지 마세요.

1.1 버그 리포트 작성하기

Ruby on Rails에서 보안 위험이 아닌 문제를 발견했다면, 이미 보고된 사례가 있는지 GitHub의 Issues에서 검색해보세요. 발견한 문제에 대해 열려있는 GitHub 이슈를 찾을 수 없다면, 다음 단계로 새로운 이슈를 생성하면 됩니다. (보안 이슈 보고에 대해서는 다음 섹션을 참조하세요.)

프레임워크에 버그가 있는지 판단하는 데 필요한 모든 정보를 포함할 수 있도록 이슈 템플릿을 제공하고 있습니다. 각 이슈는 제목과 문제에 대한 명확한 설명을 포함해야 합니다. 예상되는 동작을 보여주는 코드 샘플이나 실패하는 테스트를 포함하여 시스템 구성 등 관련된 모든 정보를 포함하도록 하세요. 당신과 다른 사람들이 쉽게 버그를 재현하고 해결 방법을 찾을 수 있도록 하는 것이 목표가 되어야 합니다.

이슈를 생성하면, "코드 레드, 미션 크리티컬, 세상이 종말로 치닫는" 종류의 버그가 아닌 이상 즉각적인 활동이 없을 수 있습니다. 이는 우리가 당신의 버그에 관심이 없다는 뜻이 아니라, 처리해야 할 이슈와 pull request가 많다는 것을 의미합니다. 같은 문제를 가진 다른 사람들이 당신의 이슈를 찾아 버그를 확인하고, 수정하는데 협력할 수 있습니다. 버그를 수정하는 방법을 알고 있다면, pull request를 생성해주세요.

1.2 실행 가능한 테스트 케이스 만들기

문제를 재현할 수 있는 방법을 제공하면 다른 사람들이 문제를 확인하고, 조사하고, 최종적으로 해결하는 데 도움이 됩니다. 실행 가능한 테스트 케이스를 제공하여 이를 수행할 수 있습니다. 이 과정을 쉽게 하기 위해, 시작점으로 사용할 수 있는 여러 버그 리포트 템플릿을 준비했습니다:

• Active Record(모델, 데이터베이스) 이슈용 템플릿: link
• Active Record(마이그레이션) 이슈 테스트용 템플릿: link
• Action Pack(컨트롤러, 라우팅) 이슈용 템플릿: link
• Action View(뷰, 헬퍼) 이슈용 템플릿: link
• Active Job 이슈용 템플릿: link
• Active Storage 이슈용 템플릿: link
• Action Mailer 이슈용 템플릿: link
• Action Mailbox 이슈용 템플릿: link
• 기타 이슈용 일반 템플릿: link

이러한 템플릿들은 테스트 케이스를 설정하기 위한 기본 코드를 포함하고 있습니다. 적절한 템플릿의 내용을 .rb 파일에 복사하고 이슈를 보여주기 위해 필요한 변경을 하세요. 터미널에서 ruby the_file.rb를 실행하여 실행할 수 있습니다. 모든 것이 잘 되면, 테스트 케이스가 실패하는 것을 볼 수 있을 것입니다.

그런 다음 실행 가능한 테스트 케이스를 gist로 공유하거나 이슈 설명에 내용을 붙여넣을 수 있습니다.

1.3 보안 문제에 대한 특별 처리

1.4 기능 요청은 어떻게 하나요?

GitHub Issues에 "기능 요청" 항목을 올리지 말아주세요. Ruby on Rails에 새로운 기능을 추가하고 싶으시다면, 직접 코드를 작성하시거나 - 다른 사람과 협력하여 코드를 작성하도록 설득하셔야 합니다. 이 가이드의 뒷부분에서 Ruby on Rails에 패치를 제안하는 자세한 방법을 확인하실 수 있습니다. GitHub Issues에 코드 없이 기능 요청 목록을 올리시면, 검토 즉시 "invalid"로 표시될 것입니다.

때로는 '버그'와 '기능' 사이의 경계가 모호할 수 있습니다. 일반적으로 기능은 새로운 동작을 추가하는 것이고, 버그는 잘못된 동작을 유발하는 것입니다. 때로는 Core 팀이 판단을 내려야 할 수도 있습니다. 다시 말해, 이러한 구분은 일반적으로 여러분의 변경사항이 어떤 패치로 릴리스될지를 결정합니다. 우리는 기능 제안을 환영합니다! 다만 maintenance 브랜치에는 백포트되지 않을 것입니다.

패치를 만들기 전에 기능 아이디어에 대한 피드백을 받고 싶으시다면, rails-core discussion board에서 논의를 시작해주세요. 아무런 응답을 받지 못할 수도 있는데, 이는 모든 사람이 무관심하다는 의미입니다. 해당 기능을 구축하는 데 관심 있는 사람을 찾을 수도 있습니다. "이것은 받아들여지지 않을 것"이라는 답변을 받을 수도 있습니다. 하지만 이곳이 새로운 아이디어를 논의하기에 적절한 곳입니다. GitHub Issues는 새로운 기능에 필요한 긴 논의를 하기에 적절한 장소가 아닙니다.

2 기존 이슈 해결 돕기

이슈를 보고하는 것을 넘어서, 여러분은 피드백을 제공함으로써 core 팀이 기존 이슈를 해결하는 데 도움을 줄 수 있습니다. Rails core 개발이 처음이시라면, 피드백을 제공하는 것이 코드베이스와 프로세스에 익숙해지는 데 도움이 될 것입니다.

GitHub Issues의 issues list를 확인해보시면, 이미 주의가 필요한 많은 이슈들을 발견하실 수 있습니다. 이러한 이슈들에 대해 여러분이 할 수 있는 일은 무엇일까요? 사실 꽤 많습니다:

2.1 버그 리포트 검증하기

우선, 버그 리포트를 검증하는 것이 도움이 됩니다. 리포트된 이슈를 본인의 컴퓨터에서 재현할 수 있나요? 만약 그렇다면, 동일한 현상이 발생한다는 코멘트를 이슈에 추가할 수 있습니다.

만약 이슈가 매우 모호하다면, 더 구체적인 것으로 좁히는 데 도움을 줄 수 있나요? 아마도 버그를 재현하기 위한 추가 정보를 제공하거나, 문제를 보여주는 데 불필요한 단계들을 제거할 수 있을 것입니다.

테스트가 없는 버그 리포트를 발견했다면, 실패하는 테스트를 제공하는 것이 매우 유용합니다. 이는 또한 소스 코드를 탐험하는 좋은 방법입니다: 기존 테스트 파일들을 살펴보면 더 많은 테스트를 작성하는 방법을 배울 수 있습니다. 새로운 테스트는 나중에 Rails 코드에 기여하기 섹션에서 설명하는 것처럼 patch 형태로 제공하는 것이 가장 좋습니다.

버그 리포트를 더 간결하게 만들거나 재현하기 쉽게 만드는 것은 - 여러분이 직접 코드를 작성하든 그렇지 않든 - 해당 버그를 수정하기 위한 코드를 작성하려는 사람들에게 도움이 됩니다.

2.2 Patch 테스트하기

GitHub를 통해 Ruby on Rails에 제출된 pull request를 검토하는 것으로도 도움을 줄 수 있습니다. 다른 사람의 변경사항을 적용하려면, 먼저 전용 branch를 생성하세요:

$ git checkout -b testing_branch

그런 다음 remote branch를 사용하여 codebase를 업데이트할 수 있습니다. 예를 들어, GitHub 사용자 JohnSmith가 fork하고 https://github.com/JohnSmith/rails 에 있는 "orange" topic branch에 push했다고 가정해보겠습니다.

$ git remote add JohnSmith https://github.com/JohnSmith/rails.git
$ git pull JohnSmith orange

그들의 pull request를 체크아웃하기 위한 대안으로 GitHub CLI tool을 사용할 수 있습니다.

그들의 branch를 적용한 후에는 테스트해보세요! 다음과 같은 사항들을 고려해보세요:

• 변경사항이 실제로 작동하나요?
• 테스트에 만족하시나요? 무엇을 테스트하는지 이해할 수 있나요? 누락된 테스트는 없나요?
• 적절한 문서 coverage를 가지고 있나요? 다른 곳의 문서도 업데이트되어야 할까요?
• 구현이 마음에 드시나요? 그들이 변경한 부분을 더 나은 방식이나 더 빠른 방식으로 구현할 수 있을까요?

pull request가 좋은 변경사항을 포함하고 있다고 판단되면, GitHub issue에 당신의 의견을 코멘트로 남기세요. 당신의 코멘트는 변경사항이 마음에 든다는 것과 어떤 점이 마음에 드는지를 표현해야 합니다. 예를 들면:

generate_finder_sql에서 코드를 재구성한 방식이 마음에 듭니다 - 훨씬 더 좋네요. 테스트도 좋아 보입니다.

만약 당신의 코멘트가 단순히 "+1"이라면, 다른 리뷰어들이 그것을 진지하게 받아들이지 않을 것입니다. pull request를 검토하는데 시간을 들였다는 것을 보여주세요.

3 Rails 문서에 기여하기

Ruby on Rails는 두 가지 주요 문서 세트가 있습니다: Ruby on Rails를 배우는데 도움을 주는 가이드와 레퍼런스 역할을 하는 API입니다.

Rails 가이드나 API 레퍼런스를 더 일관되고, 읽기 쉽게 만들거나, 누락된 정보를 추가하거나, 사실 오류를 수정하거나, 오타를 수정하거나, 최신 edge Rails로 업데이트함으로써 개선하는데 도움을 줄 수 있습니다.

이를 위해서는 GitHub의 여기에 있는 Rails 가이드 소스 파일이나 소스 코드의 RDoc 주석을 변경하세요. 그런 다음 pull request를 열어 main branch에 변경사항을 적용하세요.

문서 변경사항에 대해 CI 빌드 실행을 피하려면 pull request 제목에 [ci skip]을 사용하세요.

PR을 열면 쉬운 검토와 협업을 위해 문서 미리보기가 배포됩니다. Pull Request 페이지 하단에서 상태 체크 목록을 볼 수 있습니다. buildkite/docs-preview를 찾아 "details"를 클릭하세요.

이것은 Buildkite 빌드 페이지로 이동합니다. 작업이 성공적이었다면, 작업 목록 위에 생성된 API와 가이드 링크가 있는 주석이 표시됩니다.

문서 작업을 할 때는 API Documentation Guidelines와 Ruby on Rails Guides Guidelines를 참고해주세요.

4 Rails 가이드 번역하기

우리는 Rails 가이드 번역에 자원하는 분들을 환영합니다. 다음 단계들을 따라주세요:

• https://github.com/rails/rails를 fork하세요.
• 당신의 언어에 대한 소스 폴더를 추가하세요. 예: 이탈리아어의 경우 guides/source/it-IT.
• guides/source의 내용을 당신의 언어 디렉토리에 복사하고 번역하세요.
• HTML 파일은 자동으로 생성되므로 번역하지 마세요.

번역은 Rails 저장소에 제출되지 않으며, 위에서 설명한 대로 당신의 fork에 존재한다는 점을 유의하세요. 이는 실제로 패치를 통한 문서 유지보수는 영어로만 지속 가능하기 때문입니다.

HTML 형식으로 가이드를 생성하려면, 가이드의 의존성을 설치하고 guides 디렉토리로 cd 한 다음 다음과 같이 실행해야 합니다 (예: it-IT의 경우):

$ BUNDLE_ONLY=default:doc bundle install
$ cd guides/
$ BUNDLE_ONLY=default:doc bundle exec rake guides:generate:html GUIDES_LANGUAGE=it-IT

위 명령어를 실행하면 이탈리아어로 된 가이드를 생성합니다.

output 디렉터리에 가이드가 생성될 것입니다.

5 Rails 코드에 기여하기

5.1 개발 환경 설정하기

Ruby on Rails에 버그를 제보하는 것을 넘어서 기존 이슈를 해결하거나 직접 코드를 기여하기 위해서는 반드시 테스트 스위트를 실행할 수 있어야 합니다. 이 가이드의 이 섹션에서는 컴퓨터에서 테스트를 설정하는 방법을 배우게 됩니다.

5.1.1 GitHub Codespaces 사용하기

codespaces가 활성화된 조직의 멤버인 경우, Rails를 해당 조직으로 fork하고 GitHub의 codespaces를 사용할 수 있습니다. Codespace는 모든 필수 의존성과 함께 초기화되며 모든 테스트를 실행할 수 있게 해줍니다.

5.1.2 VS Code Remote Containers 사용하기

Visual Studio Code와 Docker가 설치되어 있다면, VS Code remote containers plugin을 사용할 수 있습니다. 이 플러그인은 저장소의 .devcontainer 설정을 읽고 Docker 컨테이너를 로컬에 빌드합니다.

5.1.3 Dev Container CLI 사용하기

또는 Docker와 npm이 설치되어 있다면, Dev Container CLI를 실행하여 커맨드 라인에서 .devcontainer 설정을 활용할 수 있습니다.

$ npm install -g @devcontainers/cli 
$ cd rails
$ devcontainer up --workspace-folder .
$ devcontainer exec --workspace-folder . bash

5.1.4 rails-dev-box 사용하기

rails-dev-box를 사용하여 개발 환경을 준비할 수도 있습니다. 하지만 rails-dev-box는 Vagrant와 Virtual Box를 사용하므로 Apple silicon이 탑재된 Mac에서는 작동하지 않습니다.

5.1.5 로컬 개발

GitHub Codespaces를 사용할 수 없는 경우, 로컬 개발 환경 설정 방법은 이 가이드를 참조하세요. 의존성 설치가 OS별로 다를 수 있기 때문에 이 방법은 어려운 방법으로 간주됩니다.

5.2 Rails Repository Clone하기

Rails repository에 코드를 기여하기 위해서는, 다음과 같이 clone해야 합니다:

$ git clone https://github.com/rails/rails.git

그리고 전용 branch를 생성하세요:

$ cd rails
$ git checkout -b my_new_branch

이 브랜치는 여러분의 로컬 컴퓨터와 GitHub의 개인 repository에만 존재하고 Rails Git repository의 일부가 되지 않을 것이기 때문에, 어떤 이름을 사용하든 크게 중요하지 않습니다.

5.3 Bundle install

필요한 gem들을 설치합니다.

$ bundle install

5.4 로컬 브랜치에서 애플리케이션 실행하기

변경사항을 테스트하기 위한 더미 Rails 앱이 필요한 경우, rails new의 --dev 플래그를 사용하면 로컬 브랜치를 사용하는 애플리케이션을 생성할 수 있습니다:

$ cd rails
$ bundle exec rails new ~/my-test-app --dev

~/my-test-app에서 생성된 애플리케이션은 로컬 branch에서 실행되며, 특히 서버 재시작 시 모든 수정사항이 반영됩니다.

JavaScript 패키지의 경우, yarn link를 사용하여 생성된 애플리케이션에서 로컬 branch를 소스로 사용할 수 있습니다:

$ cd rails/activestorage
$ yarn link
$ cd ~/my-test-app
$ yarn link "@rails/activestorage"

5.5 코드 작성하기

이제 코드를 작성할 시간입니다! Rails에 변경사항을 만들 때는 다음 사항들을 명심하세요:

• Rails 스타일과 규칙을 따르세요.
• Rails idiom과 helper를 사용하세요.
• 당신의 코드 없이는 실패하고, 코드와 함께는 통과하는 테스트를 포함하세요.
• (관련된) 문서, 다른 곳의 예제, 가이드를 업데이트하세요: 당신의 기여로 영향을 받는 모든 것을 업데이트하세요.
• 변경사항이 기능을 추가, 제거 또는 변경하는 경우 반드시 CHANGELOG 항목을 포함하세요. 버그 수정인 경우에는 CHANGELOG 항목이 필요하지 않습니다.

5.5.1 코딩 규칙을 따르세요

Rails는 간단한 코딩 스타일 규칙을 따릅니다:

• 들여쓰기는 탭이 아닌 스페이스 두 칸을 사용합니다.
• 후행 공백은 없어야 합니다. 빈 줄에는 공백이 없어야 합니다.
• private/protected 뒤에는 들여쓰기를 하고 빈 줄을 넣지 않습니다.
• Ruby >= 1.9 문법의 hash를 사용하세요. { :a => :b } 보다 { a: :b }를 선호합니다.
• and/or 보다 &&/||를 선호합니다.
• 클래스 메서드는 self.method 보다 class << self를 선호합니다.
• my_method( my_arg ) 나 my_method my_arg 대신 my_method(my_arg)를 사용하세요.
• a=b 대신 a = b를 사용하세요.
• refute 대신 assert_not 메서드를 사용하세요.
• 한 줄 블록의 경우 method{do_stuff} 대신 method { do_stuff }를 선호합니다.
• 이미 사용되고 있는 소스의 규칙을 따르세요.

위의 내용들은 가이드라인입니다 - 이를 적용할 때는 최선의 판단을 해주세요.

추가로, 우리의 일부 코딩 규칙을 성문화하기 위해 RuboCop 규칙을 정의해두었습니다. pull request를 제출하기 전에 수정한 파일에 대해 RuboCop을 로컬에서 실행할 수 있습니다:

$ bundle exec rubocop actionpack/lib/action_controller/metal/strong_parameters.rb
1개 파일 검사 중 
.

1개 파일 검사 완료, 위반사항 없음

5.6 코드 벤치마크 하기

성능에 영향을 줄 수 있는 변경사항의 경우, 코드를 벤치마크하고 영향을 측정해주세요. 사용한 벤치마크 스크립트와 결과를 공유해주시기 바랍니다. 이 정보를 커밋 메시지에 포함시키는 것을 고려해보세요. 이를 통해 향후 기여자들이 귀하의 발견을 쉽게 검증하고 여전히 관련이 있는지 판단할 수 있습니다. (예를 들어, Ruby VM의 향후 최적화로 인해 특정 최적화가 불필요해질 수 있습니다.)

관심 있는 특정 시나리오에 대해 최적화할 때, 다른 일반적인 경우들의 성능이 저하되기 쉽습니다. 따라서 실제 프로덕션 애플리케이션에서 추출한 대표적인 시나리오 목록을 대상으로 변경사항을 테스트해야 합니다.

시작점으로 benchmark template을 사용할 수 있습니다. 이 템플릿에는 benchmark-ips gem을 사용하여 벤치마크를 설정하는 기본 코드가 포함되어 있습니다. 이 템플릿은 스크립트에 인라인으로 포함될 수 있는 비교적 독립적인 변경사항을 테스트하도록 설계되었습니다.

5.7 Running Tests

Rails에서는 변경사항을 push하기 전에 전체 test suite를 실행하는 것이 일반적이지 않습니다. 특히 railties test suite는 시간이 오래 걸리며, rails-dev-box에서 권장하는 워크플로우처럼 소스 코드가 /vagrant에 마운트되어 있는 경우 특히 더 오랜 시간이 걸립니다.

타협안으로, 코드가 명백하게 영향을 미치는 부분만 테스트하고, 변경사항이 railties에 있지 않다면 영향을 받는 컴포넌트의 전체 test suite를 실행하세요. 모든 테스트가 통과한다면, 그것으로 충분히 기여할 수 있습니다. 우리는 다른 곳에서 예상치 못한 오류를 잡아내기 위한 안전망으로 Buildkite를 사용하고 있습니다.

5.7.1 Entire Rails:

전체 테스트를 실행하려면 다음과 같이 하세요:

$ cd rails
$ bundle exec rake test

5.7.2 특정 컴포넌트에 대해

특정 컴포넌트(예: Action Pack)에 대해서만 테스트를 실행할 수 있습니다. 예를 들어 Action Mailer 테스트를 실행하려면:

$ cd actionmailer
$ bin/test

5.7.3 특정 디렉토리에 대해

특정 컴포넌트의 특정 디렉토리에 대해서만 테스트를 실행할 수 있습니다 (예: Active Storage의 models). 예를 들어, /activestorage/test/models의 테스트를 실행하려면:

$ cd activestorage  
$ bin/test models

5.7.4 특정 파일만 실행하기

특정 파일에 대해서만 테스트를 실행할 수 있습니다:

$ cd actionview
$ bin/test test/template/form_helper_test.rb

5.7.5 단일 테스트 실행하기

-n 옵션을 사용해서 이름으로 단일 테스트를 실행할 수 있습니다:

$ cd actionmailer
$ bin/test test/mail_layout_test.rb -n test_explicit_class_layout

5.7.6 특정 라인에 대해

이름을 파악하는 것이 항상 쉽지는 않지만, 테스트가 시작되는 라인 번호를 알고 있다면 이 옵션을 사용할 수 있습니다:

$ cd railties
$ bin/test test/application/asset_debugging_test.rb:69

5.7.7 특정 줄 범위에서 실행하기

관련된 테스트들이 주로 가까운 위치에 정의되어 있습니다. 특정 줄 범위 내에서 테스트를 실행할 수 있습니다.

$ cd railties
$ bin/test test/application/asset_debugging_test.rb:69-100

5.7.8 특정 Seed로 테스트 실행하기

테스트 실행은 무작위 seed로 랜덤화됩니다. 무작위 테스트 실패를 경험하고 있다면, 특정 랜덤화 seed를 설정하여 실패하는 테스트 시나리오를 더 정확하게 재현할 수 있습니다.

컴포넌트의 모든 테스트 실행하기:

$ cd actionmailer
$ SEED=15002 bin/test

단일 테스트 파일 실행하기:

$ cd actionmailer
$ SEED=15002 bin/test test/mail_layout_test.rb

5.7.9 직렬로 테스트 실행하기

Action Pack과 Action View 단위 테스트는 기본적으로 병렬로 실행됩니다. 무작위 테스트 실패를 경험하고 있다면, PARALLEL_WORKERS=1을 설정하여 무작위화 시드를 지정하고 이러한 단위 테스트를 직렬로 실행할 수 있습니다.

$ cd actionview
$ PARALLEL_WORKERS=1 SEED=53708 bin/test test/template/test_case_test.rb

5.7.10 Active Record 테스팅

먼저 필요한 데이터베이스를 생성하세요. activerecord/test/config.example.yml에서 필요한 테이블 이름, 사용자 이름, 비밀번호 목록을 찾을 수 있습니다.

MySQL과 PostgreSQL의 경우 다음을 실행하는 것으로 충분합니다:

$ cd activerecord
$ bundle exec rake db:mysql:build

또는:

$ cd activerecord
$ bundle exec rake db:postgresql:build

SQLite3의 경우 이것은 필요하지 않습니다.

다음은 SQLite3에 대해서만 Active Record 테스트 스위트를 실행하는 방법입니다:

$ cd activerecord
$ bundle exec rake test:sqlite3

이제 sqlite3에서 했던 것과 같이 테스트를 실행할 수 있습니다. 각각의 태스크는 다음과 같습니다:

$ bundle exec rake test:mysql2
$ bundle exec rake test:trilogy
$ bundle exec rake test:postgresql

마지막으로,

$ bundle exec rake test

이제 세 가지를 차례대로 실행할 것입니다.

각각의 테스트를 개별적으로도 실행할 수 있습니다:

$ ARCONN=mysql2 bundle exec ruby -Itest test/cases/associations/has_many_associations_test.rb

모든 adapter에 대해 단일 테스트를 실행하려면 다음을 사용하세요:

$ bundle exec rake TEST=test/cases/associations/has_many_associations_test.rb

또한 test_jdbcmysql, test_jdbcsqlite3 또는 test_jdbcpostgresql을 실행할 수 있습니다. 더 구체적인 데이터베이스 테스트 실행에 대한 정보는 activerecord/RUNNING_UNIT_TESTS.rdoc 파일을 참고하세요.

5.7.11 테스트에서 디버거 사용하기

외부 디버거(pry, byebug 등)를 사용하려면 디버거를 설치하고 평소처럼 사용하면 됩니다. 디버거 관련 문제가 발생하면 PARALLEL_WORKERS=1을 설정하여 테스트를 순차적으로 실행하거나 -n test_long_test_name으로 단일 테스트를 실행하세요.

generator에 대한 테스트를 실행하는 경우, 디버깅 도구가 작동하려면 RAILS_LOG_TO_STDOUT=true를 설정해야 합니다.

RAILS_LOG_TO_STDOUT=true ./bin/test test/generators/actions_test.rb

5.8 Warnings

테스트 스위트는 warning이 활성화된 상태로 실행됩니다. 이상적으로는 Ruby on Rails가 어떤 warning도 발생시키지 않아야 하지만, 서드파티 라이브러리와 함께 약간의 warning이 있을 수 있습니다. warning이 있다면 무시하거나(또는 수정하세요!) warning을 새로 발생시키지 않는 패치를 제출해주세요.

Rails CI는 warning이 발생하면 오류를 발생시킵니다. 로컬에서 동일한 동작을 구현하려면 테스트 스위트 실행 시 RAILS_STRICT_WARNINGS=1을 설정하세요.

5.9 문서 업데이트하기

Ruby on Rails 가이드는 Rails 기능들에 대한 높은 수준의 개요를 제공하고, API 문서는 세부사항을 자세히 다룹니다.

만약 당신의 PR이 새로운 기능을 추가하거나 기존 기능의 동작을 변경한다면, 관련 문서를 확인하고 필요에 따라 업데이트하거나 추가하세요.

예를 들어, Active Storage의 image analyzer를 수정하여 새로운 metadata 필드를 추가한다면, Active Storage 가이드의 파일 분석하기 섹션을 이를 반영하도록 업데이트해야 합니다.

5.10 CHANGELOG 업데이트하기

CHANGELOG는 모든 릴리스의 중요한 부분입니다. Rails의 각 버전별 변경 사항 목록을 관리합니다.

기능을 추가하거나 제거하는 경우, 또는 deprecation 공지를 추가하는 경우 수정한 프레임워크의 CHANGELOG 최상단에 항목을 추가해야 합니다. 리팩토링, 사소한 버그 수정, 문서 변경은 일반적으로 CHANGELOG에 포함하지 않습니다.

CHANGELOG 항목은 변경된 내용을 요약해야 하며 작성자 이름으로 끝나야 합니다. 더 많은 공간이 필요한 경우 여러 줄을 사용할 수 있으며, 4칸 들여쓰기로 코드 예제를 첨부할 수 있습니다. 변경 사항이 특정 이슈와 관련이 있는 경우 이슈 번호를 첨부해야 합니다. 다음은 CHANGELOG 항목의 예시입니다:

*   변경된 내용을 간단히 설명하는 변경사항 요약입니다. 여러 줄을 사용할 수 있으며 
    80자 정도로 줄바꿈을 할 수 있습니다. 필요한 경우 코드 예제도 포함할 수 있습니다:

        class Foo
          def bar
            puts 'baz'
          end
        end

    코드 예제 이후에 설명을 계속할 수 있으며, 이슈 번호도 첨부할 수 있습니다.

    Fixes #1234.

    *당신의 이름*

5.11 Breaking Changes

기존 애플리케이션을 망가뜨릴 수 있는 변경사항은 breaking change로 간주됩니다. Rails 애플리케이션의 업그레이드를 쉽게 하기 위해, breaking change는 deprecation 주기를 필요로 합니다.

5.11.1 동작 제거하기

만약 breaking change가 기존 동작을 제거한다면, 먼저 기존 동작을 유지하면서 deprecation 경고를 추가해야 합니다.

예를 들어, ActiveRecord::Base의 public method를 제거하고 싶다고 가정해봅시다. 만약 main branch가 아직 릴리스되지 않은 7.0 버전을 가리키고 있다면, Rails 7.0은 deprecation 경고를 보여줄 필요가 있습니다. 이는 Rails 7.0 버전으로 업그레이드하는 모든 사람이 deprecation 경고를 볼 수 있도록 보장합니다. Rails 7.1에서는 해당 메서드를 삭제할 수 있습니다.

다음과 같이 deprecation 경고를 추가할 수 있습니다:

def deprecated_method
  ActiveRecord.deprecator.warn(<<-MSG.squish)
    `ActiveRecord::Base.deprecated_method`는 deprecate 되었으며 Rails 7.1에서 제거될 예정입니다.
  MSG
  # 기존 동작
end

5.11.2 동작 변경하기

만약 breaking change가 기존 동작을 변경한다면, framework default를 추가해야 합니다. Framework default는 앱이 새로운 기본값으로 하나씩 전환할 수 있도록 함으로써 Rails 업그레이드를 용이하게 만듭니다.

새로운 framework default를 구현하려면, 먼저 대상 framework에 accessor를 추가하여 설정을 생성하세요. 업그레이드 중에 아무것도 깨지지 않도록 하기 위해 기본값을 기존 동작으로 설정하세요.

module ActiveJob
  mattr_accessor :existing_behavior, default: true
end

이는 기존 동작을 제어하기 위한 module level accessor를 정의합니다. 기본값은 true입니다.

새로운 configuration은 새로운 동작을 조건부로 구현할 수 있도록 합니다:

def changed_method
  if ActiveJob.existing_behavior
    # 기존 동작
  else
    # 새로운 동작
  end
end

새로운 프레임워크 기본값을 설정하려면 Rails::Application::Configuration#load_defaults에서 새로운 값을 설정하세요:

def load_defaults(target_version)
  case target_version.to_s
  when "7.1"
    # ...
    if respond_to?(:active_job)
      active_job.existing_behavior = false
    end
    # ...
  end
end

업그레이드를 쉽게 하기 위해서는 새로운 기본값을 new_framework_defaults 템플릿에 추가해야 합니다. 새로운 값을 설정하는 주석 처리된 섹션을 추가하세요:

# new_framework_defaults_8_1.rb.tt

# Rails.application.config.active_job.existing_behavior = false

Rails의 Active Job이 기존의 동작 방식 대신 새로운 동작 방식을 사용하도록 설정합니다.

마지막 단계로, configuration.md의 configuration guide에 새로운 configuration을 추가하세요:

#### `config.active_job.existing_behavior

| 해당 버전부터 | 기본값 |
| --------------------- | -------------------- |
| (original)            | `true`               |
| 7.1                   | `false`              |

5.12 에디터/IDE가 생성한 파일 무시하기

일부 에디터와 IDE는 rails 폴더 내에 숨김 파일이나 폴더를 생성합니다. 이러한 파일들을 각 커밋에서 수동으로 제외하거나 Rails의 .gitignore에 추가하는 대신, global gitignore file에 추가해야 합니다.

5.13 Gemfile.lock 업데이트하기

일부 변경사항에는 dependency 업그레이드가 필요합니다. 이러한 경우, 올바른 버전의 dependency를 가져오기 위해 bundle update를 실행하고 변경사항에 Gemfile.lock 파일이 포함되어 있는지 확인하세요.

5.14 변경사항 Commit하기

컴퓨터에서 작성한 코드에 만족했다면, Git에 변경사항을 commit해야 합니다:

$ git commit -a

이것은 커밋 메시지를 작성하기 위해 에디터를 실행할 것입니다. 작성을 마치면 저장하고 닫아서 계속 진행하세요.

잘 포맷된 설명이 포함된 커밋 메시지는 다른 사람들이 변경 이유를 이해하는데 매우 도움이 되므로, 시간을 들여 작성해주시기 바랍니다.

좋은 커밋 메시지는 다음과 같습니다:

간단한 요약 (가급적 50자 이내로)

필요한 경우 더 자세한 설명을 작성하세요. 각 줄은 72자에서 줄바꿈을 해야 
합니다. 가능한 한 자세하게 설명하려고 노력하세요. 커밋 내용이 명확하다고 
생각하더라도 다른 사람에게는 명확하지 않을 수 있습니다. 관련 이슈에 이미 
있는 설명을 추가하세요. 히스토리를 확인하기 위해 웹페이지를 방문할 
필요가 없어야 합니다.

설명 섹션은 여러 단락으로 구성될 수 있습니다.

코드 예제는 4칸 들여쓰기로 포함할 수 있습니다:

    class ArticlesController
      def index
        render json: Article.limit(10)
      end
    end

글머리 기호도 추가할 수 있습니다:

- 대시(-) 또는 별표(*)로 줄을 시작하여 글머리 기호를 만듭니다 

- 72자에서 줄바꿈을 하고, 가독성을 위해 추가 줄은 2칸 들여쓰기를
  합니다

5.15 브랜치 업데이트하기

당신이 작업하는 동안 main에 다른 변경사항들이 발생했을 가능성이 매우 높습니다. main의 새로운 변경사항을 가져오려면:

$ git checkout main
$ git pull --rebase

이제 최신 변경사항 위에 패치를 다시 적용하세요:

$ git checkout my_new_branch
$ git rebase main

conflict가 없나요? 테스트는 여전히 통과하나요? 변경사항이 여전히 합리적으로 보이나요? 그렇다면 rebase된 변경사항을 GitHub에 push하세요:

$ git push --force-with-lease

rails/rails repository base에는 force pushing을 허용하지 않지만, 여러분의 fork에는 force push할 수 있습니다. rebase할 때는 history가 변경되므로 이것이 필수적입니다.

5.16 Fork

Rails GitHub repository로 이동하여 우측 상단의 "Fork" 버튼을 누르세요.

로컬 머신의 로컬 repository에 새로운 remote를 추가하세요:

$ git remote add fork https://github.com/<사용자명>/rails.git

로컬 저장소를 rails/rails에서 직접 clone했거나, 혹은 fork한 저장소에서 clone했을 수 있습니다. 다음 git 명령어들은 rails/rails를 가리키는 "rails" remote를 만들었다고 가정합니다.

$ git remote add rails https://github.com/rails/rails.git

공식 repository에서 새로운 commit과 branch를 다운로드:

$ git fetch rails

죄송하지만 번역할 원문 내용이 보이지 않습니다. Rails 가이드 문서의 번역하고자 하는 부분을 공유해 주시면 요청하신대로 번역해 드리겠습니다.

$ git checkout main
$ git rebase rails/main
$ git checkout my_new_branch
$ git rebase rails/main

여러분의 fork를 업데이트하세요:

$ git push fork main
$ git push fork my_new_branch

5.17 Pull Request 열기

방금 푸시한 Rails 저장소(예: https://github.com/your-user-name/rails)로 이동하여 상단 바의 "Pull Requests"를 클릭하세요(코드 바로 위에 있음). 다음 페이지에서 우측 상단의 "New pull request"를 클릭하세요.

Pull request는 base 저장소 rails/rails와 main 브랜치를 대상으로 해야 합니다. Head 저장소는 여러분의 작업(your-user-name/rails)이 되며, 브랜치는 여러분이 지정한 브랜치 이름이 됩니다. 준비가 되면 "create pull request"를 클릭하세요.

여러분이 추가한 변경 사항이 포함되어 있는지 확인하세요. 제공된 pull request 템플릿을 사용하여 잠재적인 패치에 대한 세부 정보를 작성하세요. 작성이 완료되면 "Create pull request"를 클릭하세요.

5.18 피드백 받기

대부분의 pull request는 merge되기 전에 몇 번의 iteration을 거칩니다. 다른 contributor들은 때때로 서로 다른 의견을 가질 수 있으며, 패치들은 merge되기 전에 수정이 필요한 경우가 많습니다.

Rails contributor 중 일부는 GitHub의 이메일 알림을 켜두었지만, 그렇지 않은 사람들도 있습니다. 게다가 Rails에서 작업하는 (거의) 모든 사람들은 자원봉사자이므로, pull request에 대한 첫 피드백을 받는 데 며칠이 걸릴 수 있습니다. 실망하지 마세요! 때로는 빠르고, 때로는 느립니다. 이것이 오픈 소스의 삶입니다.

일주일이 지났는데도 아무런 소식이 없다면, 일을 진행시키려고 시도해볼 수 있습니다. Ruby on Rails Discord server의 contributions 채널이나 rubyonrails-core discussion board를 사용할 수 있습니다. pull request에 다른 댓글을 남길 수도 있습니다. 개별 maintainer에게 직접 연락하는 것은 피하는 것이 좋습니다. 우리는 제한된 대역폭을 가지고 있어서 PR을 볼 수 없을 수도 있기 때문입니다.

pull request에 대한 피드백을 기다리는 동안, 다른 사람의 pull request를 몇 개 열어보고 피드백을 제공해보세요! 당신이 자신의 패치에 대한 피드백을 감사히 여기는 것처럼 그들도 감사히 여길 것입니다.

코드 변경을 merge할 수 있는 권한은 Core 팀과 Committer 팀에게만 있다는 점을 유의하세요. 누군가 피드백을 주고 변경사항을 "승인"했더라도, 그들은 변경사항을 merge할 수 있는 권한이나 최종 결정권이 없을 수 있습니다.

5.19 필요에 따라 반복하기

피드백을 받으면 변경이 필요할 수 있습니다. 낙담하지 마세요: 활발한 오픈소스 프로젝트에 기여하는 것의 핵심은 커뮤니티의 지식을 활용하는 것입니다. 사람들이 코드를 수정하도록 권장한다면, 수정하고 다시 제출할 가치가 있습니다. 피드백이 코드가 merge되지 않을 것이라고 한다면, gem으로 배포하는 것을 고려해볼 수 있습니다.

5.19.1 커밋 Squashing하기

우리가 요청할 수 있는 것 중 하나는 "커밋을 squash하는 것"입니다. 이는 모든 커밋을 하나의 커밋으로 결합하는 것입니다. 우리는 단일 커밋으로 된 pull request를 선호합니다. 이는 stable 브랜치로 변경사항을 백포트하기 쉽게 만들고, squashing은 잘못된 커밋을 되돌리기 쉽게 만들며, git 히스토리를 좀 더 쉽게 따라갈 수 있게 합니다. Rails는 큰 프로젝트이고, 불필요한 커밋들이 많은 노이즈를 추가할 수 있습니다.

$ git fetch rails
$ git checkout my_new_branch
$ git rebase -i rails/main

< 첫 번째 commit을 제외한 모든 commit에 대해 'squash'를 선택하세요. >
< commit 메시지를 의미있게 수정하고 모든 변경사항을 설명하세요. >

$ git push fork my_new_branch --force-with-lease

pull request를 새로고침하면 GitHub에서 업데이트된 것을 확인할 수 있습니다.

5.19.2 Pull Request 업데이트하기

때로는 이미 commit한 코드를 수정하라는 요청을 받을 수 있습니다. 여기에는 기존 commit을 수정하는 작업이 포함될 수 있습니다. 이 경우 push된 branch와 로컬 branch가 일치하지 않기 때문에 Git은 변경사항을 push하는 것을 허용하지 않습니다. 새로운 pull request를 열지 않고, 앞서 commit 스쿼시 섹션에서 설명한 것처럼 GitHub의 branch에 force push를 할 수 있습니다:

$ git commit --amend
$ git push fork my_new_branch --force-with-lease

이렇게 하면 GitHub의 branch와 pull request가 새로운 코드로 업데이트됩니다. --force-with-lease를 사용한 force push는 일반적인 -f 옵션보다 더 안전하게 remote를 업데이트합니다. -f 옵션은 로컬에 없는 remote의 작업 내용을 삭제할 수 있기 때문입니다.

5.20 Ruby on Rails의 이전 버전들

만약 다음 릴리스보다 오래된 Ruby on Rails 버전들에 수정사항을 추가하고 싶다면, 자신만의 로컬 tracking branch를 설정하고 전환해야 합니다. 다음은 7-0-stable branch로 전환하는 예시입니다:

$ git branch --track 7-0-stable rails/7-0-stable  
$ git checkout 7-0-stable

5.20.1 Backporting

Main 브랜치에 병합된 변경사항들은 Rails의 다음 메이저 릴리스를 위한 것입니다. 때로는 유지보수 릴리스에 포함하기 위해 안정 브랜치로 변경사항을 반영하는 것이 유용할 수 있습니다. 일반적으로 보안 수정과 버그 수정은 backport의 좋은 대상이 되지만, 새로운 기능이나 예상되는 동작을 변경하는 패치는 허용되지 않습니다. 확실하지 않은 경우, 시간 낭비를 피하기 위해 변경사항을 backport하기 전에 Rails 팀원과 상담하는 것이 가장 좋습니다.

먼저, main 브랜치가 최신 상태인지 확인하세요.

$ git checkout main
$ git pull --rebase

7-0-stable 과 같이 백포팅하려는 branch를 checkout하고 최신 상태인지 확인하세요:

$ git checkout 7-0-stable
$ git reset --hard origin/7-0-stable 
$ git checkout -b my-backport-branch

만약 merge된 pull request를 backport하는 경우, merge 커밋을 찾아 cherry-pick 하세요:

$ git cherry-pick -m1 MERGE_SHA

cherry-pick 과정에서 발생한 conflict를 해결하고, 변경사항을 push한 다음, backporting하려는 stable branch를 향해 PR을 생성하세요. 더 복잡한 변경사항이 있다면, cherry-pick 문서가 도움이 될 것입니다.

6 Rails Contributors

모든 기여는 Rails Contributors에서 인정받습니다.