edge
เพิ่มเติมที่ rubyonrails.org: เพิ่มเติมเกี่ยวกับ Ruby on Rails

การสนับสนุนในการพัฒนา Ruby on Rails

เอกสารนี้อธิบายถึงวิธีที่ คุณ สามารถเข้าร่วมการพัฒนาต่อเนื่องของ Ruby on Rails ได้

หลังจากอ่านเอกสารนี้คุณจะรู้:

Ruby on Rails ไม่ใช่ "framework ของคนอื่น". ในระหว่างหลายปีที่ผ่านมามีผู้ร่วมสนับสนุน Ruby on Rails มากมาย ตั้งแต่ตัวอักษรเดียวจนถึงการเปลี่ยนแปลงทางสถาปัตยกรรมขนาดใหญ่หรือการเพิ่มเติมเอกสารที่สำคัญ - ทั้งหมดเพื่อทำให้ Ruby on Rails ดีขึ้นสำหรับทุกคน แม้ว่าคุณจะไม่รู้สึกว่าคุณสามารถเขียนโค้ดหรือเอกสารได้ในขณะนี้ ยังมีวิธีอื่น ๆ ที่คุณสามารถสนับสนุนได้ เช่น รายงานปัญหาหรือทดสอบแพทช์

ตามที่กล่าวไว้ใน README ของ Rails, ทุกคนที่มีการติดต่อกับ Rails และโค้ดเบสของโครงการย่อย, ติดตามปัญหา, ห้องสนทนา, กระดานสนทนา และรายการจดหมาย คาดหวังว่าจะปฏิบัติตามรหัสจริยธรรมของ Rails code of conduct.

Chapters

  1. รายงานปัญหา
  2. การมีส่วนร่วมในเอกสาร Rails
  3. การแปล Rails Guides
  4. การสนับสนุนในการเขียนโค้ด Rails
  5. ผู้มีส่วนร่วมใน Rails

1 รายงานปัญหา

Ruby on Rails ใช้ GitHub Issue Tracking เพื่อติดตามปัญหา (โดยส่วนใหญ่เป็นข้อบกพร่องและการสนับสนุนโค้ดใหม่) หากคุณพบข้อบกพร่องใน Ruby on Rails นี่คือสถานที่ที่คุณควรเริ่มต้น คุณจะต้องสร้างบัญชี GitHub (ฟรี) เพื่อส่งปัญหา แสดงความคิดเห็นในปัญหา หรือสร้าง pull request

หมายเหตุ: ข้อบกพร่องในเวอร์ชันล่าสุดของ Ruby on Rails จะได้รับความสนใจมากที่สุด นอกจากนี้ทีมคอร์ที่ของ Rails มีความสนใจตลอดเวลาในความคิดเห็นจากผู้ที่สามารถใช้เวลาทดสอบ edge Rails (โค้ดสำหรับเวอร์ชันของ Rails ที่กำลังพัฒนาอยู่ในขณะนี้) ในส่วนท้ายของเอกสารนี้คุณจะเรียนรู้วิธีในการรับ edge Rails เพื่อทดสอบ ดูนโยบายการบำรุงรักษาของเรา maintenance policy เพื่อข้อมูลเกี่ยวกับเวอร์ชันที่รองรับ อย่าเคลื่อนย้ายปัญหาด้านความปลอดภัยไปยังตัวติดตามปัญหาของ GitHub

1.1 การสร้างรายงานข้อบกพร่อง

หากคุณพบปัญหาใน Ruby on Rails ที่ไม่เป็นความเสี่ยงต่อความปลอดภัย ค้นหา Issues ใน GitHub เพื่อดูว่ามีการรายงานปัญหานี้แล้วหรือไม่ หากคุณไม่พบปัญหาที่เปิดอยู่ใน GitHub ที่แก้ไขปัญหาที่คุณพบ ขั้นตอนถัดไปของคุณคือการ เปิดปัญหาใหม่ (ดูส่วนถัดไปสำหรับการรายงานปัญหาด้านความปลอดภัย)

เราได้เตรียมแบบฟอร์มรายงานปัญหาให้คุณ เพื่อให้คุณรวมข้อมูลที่จำเป็นทั้งหมดเพื่อตรวจสอบว่ามีข้อบกพร่องในเฟรมเวิร์กหรือไม่ แต่ละปัญหาจะต้องรวมหัวข้อและคำอธิบายชัดเจนของปัญหา ตรวจสอบให้แน่ใจว่ารวมข้อมูลที่เกี่ยวข้องให้มากที่สุดเท่าที่เป็นไปได้ เช่น ตัวอย่างโค้ดหรือการทดสอบที่ล้มเหลวที่แสดงให้เห็นพฤติกรรมที่คาดหวัง รวมถึงการกำหนดค่าระบบของคุณ จุดมุ่งหมายของคุณคือการทำให้ง่ายสำหรับคุณเอง - และผู้อื่น - ในการทำซ้ำข้อบกพร่องและค้นหาวิธีแก้ไข

เมื่อคุณเปิดปัญหา อาจจะมีการตอบสนองหรือไม่ก็ได้ ยกเว้นกรณีที่เป็น "Code Red, Mission Critical, the World is Coming to an End" แบบนั้น นั่นไม่ได้หมายความว่าเราไม่สนใจปัญหาของคุณ แต่เพียงแต่มีปัญหาและ pull request มากมายที่ต้องดำเนินการ ผู้อื่นที่มีปัญหาเดียวกันสามารถค้นหาปัญหาของคุณ และยืนยันปัญหา และอาจร่วมมือกับคุณในการแก้ไข หากคุณรู้วิธีแก้ไขข้อบกพร่อง ก็สามารถเปิด pull request ได้เลย

1.2 สร้างกรณีทดสอบที่สามารถใช้งานได้

การมีวิธีการทำซ้ำปัญหาของคุณจะช่วยให้ผู้คนสามารถยืนยัน สำรวจ และแก้ไขปัญหาของคุณได้ คุณสามารถทำได้โดยการให้ข้อมูลกรณีทดสอบที่สามารถใช้งานได้ ในการทำให้กระบวนการนี้ง่ายขึ้น เราได้เตรียมเทมเพลตรายงานข้อบกพร่องหลายรูปแบบให้คุณใช้เป็นจุดเริ่มต้น:

  • เทมเพลตสำหรับปัญหา Active Record (โมเดล, ฐานข้อมูล): gem / main
  • เทมเพลตสำหรับการทดสอบ Active Record (การเคลื่อนย้าย): gem / main
  • เทมเพลตสำหรับปัญหา Action Pack (คอนโทรลเลอร์, เส้นทาง): gem / main
  • เทมเพลตสำหรับปัญหา Active Job: gem / main
  • เทมเพลตสำหรับปัญหา Active Storage: gem / main
  • เทมเพลตสำหรับปัญหา Action Mailbox: gem / main
  • เทมเพลตทั่วไปสำหรับปัญหาอื่น ๆ: gem / main

เทมเพลตเหล่านี้รวมถึงโค้ดต้นแบบสำหรับการตั้งค่ากรณีทดสอบเพื่อทดสอบกับรุ่นที่เผยแพร่ของ Rails (*_gem.rb) หรือ edge Rails (*_main.rb)

คัดลอกเนื้อหาของเทมเพลตที่เหมาะสมลงในไฟล์ .rb และทำการเปลี่ยนแปลงที่จำเป็นเพื่อสาธิตปัญหา คุณสามารถเรียกใช้ได้โดยรัน ruby the_file.rb ในเทอร์มินัลของคุณ หากทุกอย่างเป็นไปตามที่คาดหวัง คุณควรเห็นกรณีทดสอบของคุณล้มเหลว

คุณสามารถแบ่งปันกรณีทดสอบที่สามารถใช้งานได้เป็น gist หรือวางเนื้อหาลงในคำอธิบายของปัญหา

1.3 การจัดการเฉพาะสำหรับปัญหาด้านความปลอดภัย

คำเตือน: โปรดอย่ารายงานช่องโหว่ด้านความปลอดภัยผ่านทางรายงานปัญหาใน GitHub ที่เป็นสาธารณะ หน้า นโยบายความปลอดภัยของ Rails ระบุขั้นตอนการดำเนินการสำหรับปัญหาด้านความปลอดภัย

1.4 แล้วถ้าต้องการคุณสมบัติใหม่?

โปรดอย่าใส่รายการ "คำขอคุณสมบัติ" เข้าไปใน GitHub Issues หากมีคุณสมบัติใหม่ที่คุณต้องการให้เพิ่มใน Ruby on Rails คุณจะต้องเขียนโค้ดเอง - หรือโน้มน้าวให้คนอื่นร่วมงานกับคุณในการเขียนโค้ด ในภายหลังในคู่มือนี้ คุณจะพบคำแนะนำอย่างละเอียดสำหรับการเสนอแพทช์ให้กับ Ruby on Rails หากคุณใส่รายการสิ่งที่ต้องการใน GitHub Issues โดยไม่มีโค้ด คุณคาดว่าจะถูกทำเครื่องหมาย "ไม่ถูกต้อง" เมื่อได้รับการตรวจสอบ

บางครั้ง ขีดเส้นระหว่าง 'ข้อบกพร่อง' และ 'คุณสมบัติ' เป็นเรื่องที่ยากต่อการวาด โดยทั่วไป คุณสมบัติคืออะไรก็ตามที่เพิ่มพฤติกรรมใหม่ ในขณะที่ข้อบกพร่องคืออะไรก็ตามที่ทำให้เกิดพฤติกรรมไม่ถูกต้อง บางครั้งทีมคอร์จะต้องตัดสินใจ อย่างไรก็ตาม การแยกแยะนั้นมักจะกำหนดว่าการแก้ไขของคุณจะถูกเผยแพร่พร้อมกับซับซ้อน! เราชอบการส่งคุณสมบัติ! แต่มันจะไม่ถูกนำกลับไปใช้กับสาขาการบำรุงรักษา

หากคุณต้องการคำแนะนำเกี่ยวกับไอเดียสำหรับคุณสมบัติก่อนที่จะทำงานเพื่อสร้างแพทช์ โปรดเริ่มการสนทนาใน กระดานสนทนา rails-core คุณอาจจะไม่ได้รับการตอบสนอง ซึ่งหมายความว่าทุกคนไม่สนใจ คุณอาจพบคนที่สนใจที่จะสร้างคุณสมบัตินั้น ๆ คุณอาจได้รับ "ไม่อนุญาต" แต่นี่เป็นสถานที่ที่เหมาะสมในการสนทนาเกี่ยวกับไอเดียใหม่ GitHub Issues ไม่ใช่สถานที่ที่ดีมากสำหรับการสนทนาที่ซับซ้อนและยาวนานที่คุณสมบัติใหม่ต้องการ หากคุณตรวจสอบ รายการปัญหา ใน GitHub Issues คุณจะพบว่ามีปัญหาหลายรายการที่ต้องการความสนใจอยู่แล้ว คุณสามารถทำอะไรได้กับเหล่านี้บ้าง? จริงๆ แล้วมีอยู่เยอะมาก:

1.5 การตรวจสอบรายงานข้อบกพร่อง

เริ่มต้นด้วยการตรวจสอบรายงานข้อบกพร่อง การทดสอบสามารถทำซ้ำได้หรือไม่? หากใช่ คุณสามารถเพิ่มความคิดเห็นในรายการปัญหาว่าคุณก็เห็นเหมือนกัน

หากมีปัญหาที่ไม่ชัดเจนมาก คุณสามารถช่วยลดขอบเขตของปัญหาให้มีความเฉพาะเจาะจงมากขึ้นได้หรือไม่? บางครั้งคุณอาจจะสามารถให้ข้อมูลเพิ่มเติมเพื่อทดสอบข้อบกพร่อง หรือบางครั้งคุณอาจจะลดขั้นตอนที่ไม่จำเป็นที่ไม่ต้องการในการสาธิตปัญหา

หากคุณพบรายงานข้อบกพร่องที่ไม่มีการทดสอบ การมีการทดสอบที่ล้มเหลวจะมีประโยชน์อย่างมาก นี่เป็นวิธีที่ดีในการสำรวจรหัสต้นฉบับ: การดูไฟล์ทดสอบที่มีอยู่จะช่วยให้คุณเรียนรู้วิธีการเขียนการทดสอบเพิ่มเติม การทดสอบใหม่ที่ดีที่สุดควรเป็นการมีส่วนร่วมในรูปแบบของแพทช์ ตามที่อธิบายในภายหลังในส่วน การมีส่วนร่วมในรหัส Rails

การทำให้รายงานข้อบกพร่องสั้นกระชับหรือง่ายต่อการทดสอบจะช่วยให้ผู้พยากรณ์ที่พยายามเขียนรหัสเพื่อแก้ไขข้อบกพร่องเหล่านั้นมีความสะดวกมากขึ้น - ไม่ว่าคุณจะเขียนรหัสเองหรือไม่ก็ตาม

1.6 การทดสอบแพทช์

คุณยังสามารถช่วยเหลือได้โดยตรวจสอบ pull request ที่ถูกส่งไปยัง Ruby on Rails ผ่าน GitHub ในการนำเสนอการเปลี่ยนแปลงของคนอื่น ๆ ก่อนที่จะนำมาใช้งาน คุณสามารถสร้างแฟ้มสำหรับการทดสอบเฉพาะได้โดยใช้คำสั่งต่อไปนี้:

$ git checkout -b testing_branch

จากนั้นคุณสามารถใช้แฟ้มระยะไกลของพวกเขาเพื่ออัปเดตฐานรหัสของคุณ ตัวอย่างเช่น สมมุติว่าผู้ใช้ GitHub ชื่อ JohnSmith ได้ทำการ fork และ push ไปยังแฟ้มหัวข้อ "orange" ที่ตั้งอยู่ที่ https://github.com/JohnSmith/rails

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

วิธีทางเลือกหนึ่งในการเพิ่มแฟ้มระยะไกลของพวกเขาในการตรวจสอบคือการใช้เครื่องมือ GitHub CLI เพื่อเช็คเอาท์ pull request ของพวกเขา

หลังจากนำแฟ้มของพวกเขามาใช้ ลองทดสอบดู! นี่คือสิ่งที่คุณควรคิด:

  • การเปลี่ยนแปลงทำงานจริงหรือไม่?
  • คุณพอใจกับการทดสอบหรือไม่? คุณสามารถติดตามว่าพวกเขากำลังทดสอบอะไรหรือไม่? มีการทดสอบที่ขาดหรือไม่?
  • มีความครอบคลุมของเอกสารที่เหมาะสมหรือไม่? ควรอัปเดตเอกสารที่อื่นหรือไม่?
  • คุณชอบวิธีการดำเนินการหรือไม่? คุณคิดว่ามีวิธีที่ดีกว่าหรือเร็วกว่าในการดำเนินการบางส่วนของการเปลี่ยนแปลงของพวกเขาหรือไม่?

เมื่อคุณพอใจกับ pull request ที่มีการเปลี่ยนแปลงที่ดี ควรแสดงความคิดเห็นในปัญหา GitHub เพื่อแสดงความคิดเห็นของคุณ ควรระบุว่าคุณชอบการเปลี่ยนแปลงและคุณชอบสิ่งใดในการเปลี่ยนแปลงนั้น อย่างเช่น:

ฉันชอบวิธีที่คุณได้จัดโครงสร้างรหัสใน generate_finder_sql - ดีมาก การทดสอบดูดีเช่นกัน

หากความคิดเห็นของคุณเพียงแค่อ่าน "+1" แล้วคุณอาจจะพบว่าผู้ตรวจสอบอื่น ๆ ไม่ค่อยสนใจ แสดงให้เห็นว่าคุณใช้เวลาในการตรวจสอบ pull request

2 การมีส่วนร่วมในเอกสาร Rails

Ruby on Rails มีเอกสารหลักสองชุดหลัก: คู่มือที่ช่วยให้คุณเรียนรู้เกี่ยวกับ Ruby on Rails และ API ที่เป็นแหล่งอ้างอิง คุณสามารถช่วยปรับปรุงเอกสารแนะนำ Rails หรือ API reference ได้โดยทำให้มันสอดคล้องกันมากขึ้น สอดคล้อง หรืออ่านง่ายขึ้น โดยการเพิ่มข้อมูลที่ขาดหายไป แก้ไขข้อผิดพลาดทางจริง แก้ไขการพิมพ์ผิด หรืออัปเดตให้เข้ากับ Rails เวอร์ชันล่าสุด

ในการทำเช่นนั้น ให้ทำการเปลี่ยนแปลงไฟล์ต้นฉบับของ Rails guides (ที่อยู่ ที่นี่ บน GitHub) หรือคอมเมนต์ RDoc ในโค้ดต้นฉบับ จากนั้นเปิด pull request เพื่อนำการเปลี่ยนแปลงของคุณไปใช้กับสาขาหลัก

เมื่อทำงานกับเอกสาร โปรดทราบ API Documentation Guidelines และ Ruby on Rails Guides Guidelines

3 การแปล Rails Guides

เรายินดีที่จะมีผู้ที่อาสาที่จะแปล Rails guides แค่ทำตามขั้นตอนเหล่านี้:

  • Fork https://github.com/rails/rails
  • เพิ่มโฟลเดอร์ source สำหรับภาษาของคุณ เช่น guides/source/it-IT สำหรับภาษาอิตาลี
  • คัดลอกเนื้อหาของ guides/source ไปยังโฟลเดอร์ภาษาของคุณและแปลเนื้อหา
  • อย่าแปลไฟล์ HTML เนื่องจากมันถูกสร้างขึ้นโดยอัตโนมัติ

โปรดทราบว่าการแปลไม่ได้ถูกส่งให้กับเก็บรักษาของ Rails งานของคุณอยู่ใน fork ของคุณตามที่อธิบายไว้ข้างต้น นี่เพราะว่าในการปฏิบัติจริง การบำรุงรักษาเอกสารผ่านทางแพทช์เป็นเรื่องที่ยากที่จะทำได้เฉพาะเป็นภาษาอังกฤษเท่านั้น

ในการสร้างเอกสารแบบ HTML คุณจะต้องติดตั้ง dependencies ของเอกสาร ให้เข้าไปในไดเรกทอรี guides แล้วรัน (ตัวอย่างเช่นสำหรับ it-IT):

# ติดตั้งเฉพาะ gem ที่จำเป็นสำหรับเอกสาร หากต้องการยกเลิกให้รัน: bundle config --delete without
$ bundle install --without job cable storage ujs test db
$ cd guides/
$ bundle exec rake guides:generate:html GUIDES_LANGUAGE=it-IT

นี้จะสร้างเอกสารในไดเรกทอรี output

หมายเหตุ: Redcarpet Gem ไม่สามารถทำงานกับ JRuby ได้

ความพยายามในการแปลที่เรารู้จัก (เวอร์ชันต่าง ๆ):

4 การสนับสนุนในการเขียนโค้ด Rails

4.1 การตั้งค่าสภาพแวดล้อมการพัฒนา

เพื่อที่จะเข้าสู่ขั้นตอนของการช่วยแก้ปัญหาที่มีอยู่หรือการสนับสนุนในการเขียนโค้ดของคุณเองให้กับ Ruby on Rails คุณ ต้อง สามารถรันชุดทดสอบของ Rails ได้ ในส่วนนี้ของเอกสาร คุณจะเรียนรู้วิธีการตั้งค่าการทดสอบบนคอมพิวเตอร์ของคุณ

4.1.1 การใช้ GitHub Codespaces

หากคุณเป็นสมาชิกขององค์กรที่เปิดใช้งาน codespaces คุณสามารถ fork Rails เข้าสู่องค์กรนั้นและใช้ codespaces บน GitHub Codespace จะถูกเริ่มต้นด้วย dependencies ที่จำเป็นทั้งหมดและช่วยให้คุณรันทดสอบทั้งหมด

4.1.2 การใช้ VS Code Remote Containers

หากคุณมี Visual Studio Code และ Docker ติดตั้งอยู่ คุณสามารถใช้ปลั๊กอิน VS Code remote containers plugin ปลั๊กอินจะอ่านการกำหนดค่า .devcontainer ในเก็บรักษาและสร้างคอนเทนเนอร์ Docker ในเครื่องของคุณ

4.1.3 การใช้ Dev Container CLI

หรือถ้าคุณมี Docker และ npm ติดตั้งอยู่ คุณสามารถรัน Dev Container CLI เพื่อใช้ .devcontainer จาก command line

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

4.1.4 การใช้ rails-dev-box

คุณยังสามารถใช้ rails-dev-box เพื่อเตรียมสภาพแวดล้อมการพัฒนาได้เช่นกัน อย่างไรก็ตาม rails-dev-box ใช้ Vagrant และ Virtual Box ซึ่งจะไม่ทำงานบน Macs ที่มีชิป Apple silicon

4.1.5 การพัฒนาในเครื่องที่ใช้ในการพัฒนา

เมื่อคุณไม่สามารถใช้ GitHub Codespaces ดูคู่มืออื่นเพื่อวิธีการติดตั้งการพัฒนาในเครื่องที่ใช้ในการพัฒนา นี่ถือเป็นวิธีที่ยากเพราะการติดตั้ง dependencies อาจเป็นเรื่องที่เฉพาะกับระบบปฏิบัติการ

4.2 คลังรหัส Rails

เพื่อที่จะสามารถมีส่วนร่วมในการเขียนโค้ด คุณต้องคลังรหัส Rails:

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

และสร้าง branch ที่เฉพาะเจาะจง:

$ cd rails
$ git checkout -b my_new_branch

ไม่สำคัญว่าคุณจะใช้ชื่ออะไร เพราะ branch นี้จะมีอยู่เฉพาะในคอมพิวเตอร์ของคุณและคลังรหัสส่วนบุคคลของคุณบน GitHub เท่านั้น มันจะไม่เป็นส่วนหนึ่งของคลังรหัส Git ของ Rails

4.3 ติดตั้ง Bundle

ติดตั้ง gems ที่จำเป็น

$ bundle install

4.4 รันแอปพลิเคชันกับ Branch ในเครื่องของคุณ

ในกรณีที่คุณต้องการแอปพลิเคชัน Rails เพื่อทดสอบการเปลี่ยนแปลง คุณสามารถใช้ --dev flag ของ rails new เพื่อสร้างแอปพลิเคชันที่ใช้ branch ในเครื่องของคุณ:

$ 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"

4.5 เขียนโค้ดของคุณ

ตอนนี้เป็นเวลาที่คุณจะเขียนโค้ดบางส่วน! เมื่อทำการเปลี่ยนแปลงสำหรับ Rails นี่คือสิ่งที่คุณควรจะมีในใจ:

  • ปฏิบัติตามรูปแบบและสรรพนามของ Rails
  • ใช้รูปแบบและช่วยเหลือของ Rails
  • รวมการทดสอบที่ล้มเหลวหากไม่มีโค้ดของคุณและผ่านกับโค้ดของคุณ
  • อัปเดตเอกสาร (ที่อยู่รอบๆ) ตัวอย่างอื่น ๆ และคู่มือ: สิ่งใดที่ได้รับผลกระทบจากการมีส่วนร่วมของคุณ
  • หากการเปลี่ยนแปลงเพิ่มเติม ลบหรือเปลี่ยนฟีเจอร์ ตรวจสอบให้แน่ใจว่ามีการเพิ่มรายการ CHANGELOG หากการเปลี่ยนแปลงของคุณเป็นการแก้ไขข้อบกพร่อง ไม่จำเป็นต้องมีรายการ CHANGELOG

เคล็ดลับ: การเปลี่ยนแปลงที่เป็นเพียงการปรับแต่งและไม่เพิ่มอะไรที่สำคัญต่อความเสถียรภาพ ฟังก์ชันหรือความสามารถในการทดสอบของ Rails โดยทั่วไปจะไม่ได้รับการยอมรับ (อ่านเพิ่มเติมเกี่ยวกับเหตุผลของเราในการตัดสินใจนี้).

4.5.1 ปฏิบัติตามกฎเกณฑ์การเขียนโค้ด

Rails ปฏิบัติตามกฎเกณฑ์การเขียนโค้ดที่เรียบง่าย:

  • สองช่องว่าง ไม่มีแท็บ (สำหรับการเยื้อง)
  • ไม่มีช่องว่างที่เหลืออยู่ บรรทัดว่างไม่ควรมีช่องว่าง
  • เยื้องและไม่มีบรรทัดว่างหลังจาก private/protected
  • ใช้ไวยากรณ์ Ruby >= 1.9 สำหรับ hashes ให้ใช้ { a: :b } แทน { :a => :b }
  • ใช้ &&/|| แทน and/or
  • ใช้ class << self แทน self.method สำหรับเมธอดของคลาส
  • ใช้ my_method(my_arg) ไม่ใช่ my_method( my_arg ) หรือ my_method my_arg
  • ใช้ a = b และไม่ใช้ a=b
  • ใช้เมธอด assert_not แทน refute
  • ใช้ method { do_stuff } แทน method{do_stuff} สำหรับบล็อกแบบหนึ่งบรรทัด
  • ปฏิบัติตามกฎเกณฑ์ในแหล่งที่คุณเห็นใช้แล้ว

ข้อกำหนดดังกล่าวเป็นแนวทาง - โปรดใช้การตัดสินใจที่ดีที่สุดของคุณในการใช้งาน นอกจากนี้เรายังมีกฎของ RuboCop ที่กำหนดเพื่อรวมรวมกฎการเขียนโค้ดของเราบางส่วน คุณสามารถรัน RuboCop ในเครื่องของคุณเพื่อตรวจสอบไฟล์ที่คุณได้แก้ไขก่อนที่จะส่ง pull request:

$ bundle exec rubocop actionpack/lib/action_controller/metal/strong_parameters.rb
Inspecting 1 file
.

1 file inspected, no offenses detected

สำหรับไฟล์ CoffeeScript และ JavaScript ของ rails-ujs คุณสามารถรัน npm run lint ในโฟลเดอร์ actionview ได้

4.5.2 การตรวจสอบการสะกด

เราใช้ misspell ที่เขียนขึ้นโดยใช้ภาษา Golang เพื่อตรวจสอบการสะกดคำด้วย GitHub Actions แก้ไขคำภาษาอังกฤษที่ผิดได้อย่างรวดเร็วด้วย misspell โดย misspell แตกต่างจากสะกดคำอื่นๆ เพราะว่าไม่ใช้พจนานุกรมที่กำหนดเอง คุณสามารถรัน misspell ในเครื่องของคุณตรวจสอบไฟล์ทั้งหมดได้ดังนี้:

$ find . -type f | xargs ./misspell -i 'aircrafts,devels,invertions' -error

ตัวเลือกหรือ flag ที่น่าสนใจของ misspell ได้แก่:

  • -i string: ระบุคำที่ต้องการละเว้นการแก้ไขคัดลอกที่คั่นด้วยเครื่องหมายจุลภาค
  • -w: เขียนทับไฟล์ด้วยการแก้ไข (ค่าเริ่มต้นคือแสดงผลเท่านั้น)

เรายังรัน codespell ด้วย GitHub Actions เพื่อตรวจสอบการสะกดคำและ codespell ทำงานกับ พจนานุกรมที่กำหนดเองเล็กน้อย codespell เขียนขึ้นด้วยภาษา Python และคุณสามารถรันได้ดังนี้:

$ codespell --ignore-words=codespell.txt

4.6 เบนช์มาร์กโค้ดของคุณ

สำหรับการเปลี่ยนแปลงที่อาจมีผลต่อประสิทธิภาพ โปรดเทสเบนช์มาร์กโค้ดของคุณและวัดผลที่เกิดขึ้น โปรดแชร์สคริปต์เบนช์มาร์กที่คุณใช้รวมถึงผลลัพธ์ด้วย คุณควรพิจารณาเพิ่มข้อมูลเหล่านี้ในข้อความ commit เพื่อให้ผู้ร่วมพัฒนาในอนาคตสามารถตรวจสอบข้อความของคุณและกำหนดว่ายังเป็นข้อมูลที่สำคัญหรือไม่ (ตัวอย่างเช่นการปรับปรุงใน Ruby VM อาจทำให้การปรับปรุงบางอย่างไม่จำเป็นอีกต่อไป)

เมื่อทำการปรับปรุงสำหรับสถานการณ์ที่คุณสนใจ มันอาจทำให้ประสิทธิภาพลดลงสำหรับกรณีทั่วไปอื่นๆ ดังนั้นคุณควรทดสอบการเปลี่ยนแปลงของคุณในรายการสถานการณ์ที่แท้จริง โดยที่คุณสามารถดึงมาจากแอปพลิเคชันในโลกจริง

คุณสามารถใช้ เทมเพลตเบนช์มาร์ก เป็นจุดเริ่มต้น มันรวมโค้ดต้นแบบเพื่อตั้งค่าเบนช์มาร์กโดยใช้ gem benchmark-ips เทมเพลตถูกออกแบบสำหรับการทดสอบการเปลี่ยนแปลงที่เป็นอิสระที่สามารถแทรกลงในสคริปต์ได้

4.7 การรันเทส

ไม่เคยเป็นประเพณีใน Rails ที่จะรันชุดเทสทั้งหมดก่อนการดันการเปลี่ยนแปลง ชุดเทสของ railties โดยเฉพาะใช้เวลานาน และจะใช้เวลานานยิ่งขึ้นถ้าโค้ดต้นฉบับถูกติดตั้งใน /vagrant เหมือนกับกระบวนการที่แนะนำกับ rails-dev-box

เป็นการประนีประนอม ทดสอบสิ่งที่โค้ดของคุณมีผลต่อโดยชัดเจน และหากการเปลี่ยนแปลงไม่ได้อยู่ใน railties ให้รันชุดเทสทั้งหมดของส่วนที่ได้รับผลกระทบ หากผ่านทดสอบทั้งหมดนั้นเพียงพอที่จะเสนอการมีส่วนร่วมของคุณ เรามี Buildkite เป็นเครือข่ายรักษาความปลอดภัยในการตรวจจับข้อผิดพลาดที่ไม่คาดคิดในส่วนอื่นๆ

4.7.1 Rails ทั้งหมด:

ในการรันเทสทั้งหมด ให้ใช้คำสั่ง:

$ cd rails
$ bundle exec rake test

4.7.2 สำหรับส่วนประกอบที่เฉพาะเจาะจง

คุณสามารถรันเทสสำหรับส่วนประกอบที่เฉพาะเจาะจงได้ (เช่น Action Pack) ตัวอย่างเช่น ในการรันเทส Action Mailer:

$ cd actionmailer
$ bin/test

4.7.3 สำหรับไดเรกทอรีที่เฉพาะเจาะจง

คุณสามารถรันเทสสำหรับไดเรกทอรีที่เฉพาะเจาะจงของส่วนประกอบที่เฉพาะเจาะจง (เช่นโมเดลใน Active Storage) ตัวอย่างเช่น ในการรันเทสใน /activestorage/test/models: bash $ cd activestorage $ bin/test models

4.7.4 สำหรับไฟล์ที่เฉพาะเจาะจง

คุณสามารถเรียกใช้การทดสอบสำหรับไฟล์ที่เฉพาะเจาะจงได้:

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

4.7.5 การเรียกใช้การทดสอบเพียงรายการเดียว

คุณสามารถเรียกใช้การทดสอบเพียงรายการเดียวโดยใช้ตัวเลือก -n:

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

4.7.6 สำหรับบรรทัดที่เฉพาะเจาะจง

การหาชื่อไม่ใช่เรื่องง่ายเสมอไป แต่หากคุณทราบหมายเลขบรรทัดที่เริ่มต้นของการทดสอบของคุณ ตัวเลือกนี้เหมาะสำหรับคุณ:

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

4.7.7 การเรียกใช้การทดสอบด้วย Seed เฉพาะ

การทดสอบจะถูกสุ่มด้วย Seed สุ่ม หากคุณพบข้อผิดพลาดที่เกิดขึ้นแบบสุ่ม คุณสามารถทำซ้ำสถานการณ์การทดสอบที่ผิดพลาดได้อย่างแม่นยำโดยการตั้งค่า Seed สุ่มเฉพาะ

การเรียกใช้การทดสอบทั้งหมดสำหรับคอมโพเนนต์:

$ cd actionmailer
$ SEED=15002 bin/test

การเรียกใช้ไฟล์การทดสอบเดียว:

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

4.7.8 การเรียกใช้การทดสอบเป็น Serial

การทดสอบหน่วย Action Pack และ Action View ทำงานแบบพร้อมกันโดยค่าเริ่มต้น หากคุณพบข้อผิดพลาดที่เกิดขึ้นแบบสุ่ม คุณสามารถตั้งค่า Seed สุ่มและให้การทดสอบหน่วยเหล่านี้ทำงานแบบ Serial โดยการตั้งค่า PARALLEL_WORKERS=1

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

4.7.9 การทดสอบ 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 ไม่จำเป็นต้องทำเช่นนั้น

นี่คือวิธีการเรียกใช้ชุดทดสอบ Active Record เฉพาะสำหรับ SQLite3:

$ 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

ในการเรียกใช้การทดสอบเดียวกันสำหรับทุกตัวอักษร ใช้:

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

คุณยังสามารถเรียกใช้ test_jdbcmysql, test_jdbcsqlite3 หรือ test_jdbcpostgresql ได้เช่นกัน ดูไฟล์ activerecord/RUNNING_UNIT_TESTS.rdoc เพื่อข้อมูลเพิ่มเติมเกี่ยวกับการเรียกใช้การทดสอบฐานข้อมูลที่เป้าหมายมากขึ้น

4.7.10 การใช้ Debuggers กับการทดสอบ

ในการใช้ตัวตรวจสอบภายนอก (pry, byebug, เป็นต้น) ติดตั้งตัวตรวจสอบและใช้งานเหมือนเดิม หากเกิดปัญหาในตัวตรวจสอบ ให้เรียกใช้การทดสอบในลักษณะ Serial โดยการตั้งค่า PARALLEL_WORKERS=1 หรือเรียกใช้การทดสอบเดียวด้วย -n test_long_test_name

4.8 คำเตือน

ชุดทดสอบทำงานโดยเปิดใช้งานคำเตือน อย่างไรก็ตาม Ruby on Rails ควรไม่มีการแสดงคำเตือน แต่อาจมีบางอย่าง รวมถึงบางส่วนจากไลบรารีภายนอก กรุณาละเว้น (หรือแก้ไข!) หากมี และส่งแพทช์ที่ไม่มีการแสดงคำเตือนใหม่

Rails CI จะเรียกใช้การแสดงคำเตือนหากมีการแสดงคำเตือน ในการดำเนินการเดียวกัน ตั้งค่า RAILS_STRICT_WARNINGS=1 เมื่อเรียกใช้ชุดทดสอบ

4.9 การอัปเดตเอกสาร

เอกสารแนะนำ Ruby on Rails guides ให้ภาพรวมระดับสูงของคุณลักษณะของ Rails ในขณะที่เอกสาร API API documentation ศึกษาลึกลงไปยังรายละเอียด

หาก PR ของคุณเพิ่มคุณลักษณะใหม่หรือเปลี่ยนวิธีการทำงานของคุณลักษณะที่มีอยู่ ตรวจสอบเอกสารที่เกี่ยวข้องและอัปเดตหรือเพิ่มเติมตามความจำเป็น

ตัวอย่างเช่น หากคุณแก้ไขตัววิเคราะห์ภาพ Active Storage เพื่อเพิ่มฟิลด์ metadata ใหม่ คุณควรอัปเดตส่วน Analyzing Files ของ Active Storage guide เพื่อสะท้อนความเปลี่ยนแปลงนั้น

4.10 การอัปเดต CHANGELOG

CHANGELOG เป็นส่วนสำคัญของทุกการเปิดตัว มันเก็บรายการการเปลี่ยนแปลงสำหรับทุกเวอร์ชันของ Rails

คุณควรเพิ่มรายการ ไปที่ด้านบน ของ CHANGELOG ของเฟรมเวิร์กที่คุณแก้ไขหากคุณกำลังเพิ่มหรือลบคุณลักษณะหรือเพิ่มประกาศการเลิกใช้ การเปลี่ยนแปลงขนาดเล็ก การแก้ไขข้อบกพร่องเล็ก และการเปลี่ยนแปลงเอกสารทั่วไปไม่ควรไปที่ CHANGELOG

รายการ CHANGELOG ควรสรุปสิ่งที่เปลี่ยนแปลงและควรจบด้วยชื่อผู้เขียน คุณสามารถใช้หลายบรรทัดหากคุณต้องการเพิ่มพื้นที่เพิ่มเติม และคุณสามารถแนบตัวอย่างโค้ดที่เยื้องด้วย 4 ช่องว่าง หากการเปลี่ยนแปลงเกี่ยวข้องกับปัญหาที่เฉพาะเจาะจงคุณควรแนบหมายเลขปัญหา ต่อไปนี้คือตัวอย่างรายการ CHANGELOG:

*   สรุปการเปลี่ยนแปลงที่อธิบายสั้นๆว่ามีการเปลี่ยนแปลงอะไร คุณสามารถใช้หลายบรรทัดและแบ่งบรรทัดเมื่อถึงรอบ 80 อักขระ ตัวอย่างโค้ดก็ได้ถ้าจำเป็น:

        class Foo
          def bar
            puts 'baz'
          end
        end

    คุณสามารถดำเนินการต่อหลังจากตัวอย่างโค้ด และคุณสามารถแนบหมายเลขปัญหาได้

    แก้ไข #1234.

    *ชื่อของคุณ*

ชื่อของคุณสามารถเพิ่มโดยตรงหลังคำสุดท้ายหากไม่มีตัวอย่างโค้ดหรือย่อหน้าหลายย่อหน้า มิฉะนั้น ควรสร้างย่อหน้าใหม่

4.11 การเปลี่ยนแปลงที่ทำให้เกิดข้อบกพร่อง

ทุกครั้งที่มีการเปลี่ยนแปลงที่อาจทำให้เกิดข้อบกพร่องในแอปพลิเคชันที่มีอยู่แล้ว จะถือว่าเป็นการเปลี่ยนแปลงที่ทำให้เกิดข้อบกพร่อง ในการอัปเกรดแอปพลิเคชัน Rails เพื่อให้ง่ายขึ้น การเปลี่ยนแปลงที่ทำให้เกิดข้อบกพร่องต้องผ่านกระบวนการเลิกใช้

4.11.1 การลบพฤติกรรม

หากการเปลี่ยนแปลงที่ทำให้เกิดข้อบกพร่องลบพฤติกรรมที่มีอยู่ คุณจะต้องเพิ่มคำเตือนการเลิกใช้ในขณะที่ยังคงมีพฤติกรรมที่มีอยู่

เป็นตัวอย่างเช่น สมมติว่าคุณต้องการลบเมธอดสาธารณะบน ActiveRecord::Base หากสาขาหลักชี้ไปที่เวอร์ชันที่ยังไม่ได้เผยแพร่ 7.0 Rails 7.0 จะต้องแสดงคำเตือนการเลิกใช้ นี้จะทำให้แน่ใจว่าผู้ที่อัปเกรดไปยังเวอร์ชันใดก็ตามของ Rails 7.0 จะเห็นคำเตือนการเลิกใช้ ใน Rails 7.1 เมธอดสามารถลบได้

คุณสามารถเพิ่มคำเตือนการเลิกใช้ต่อไปนี้:

def deprecated_method
  ActiveRecord.deprecator.warn(<<-MSG.squish)
    `ActiveRecord::Base.deprecated_method` is deprecated and will be removed in Rails 7.1.
  MSG
  # พฤติกรรมที่มีอยู่
end

4.11.2 การเปลี่ยนแปลงพฤติกรรม

หากการเปลี่ยนแปลงที่ทำให้เกิดข้อบกพร่องเปลี่ยนพฤติกรรมที่มีอยู่ คุณจะต้องเพิ่มค่าเริ่มต้นของเฟรมเวิร์ก การตั้งค่าเริ่มต้นช่วยให้การอัปเกรด Rails เป็นเรื่องง่ายโดยอนุญาตให้แอปพลิเคชันสามารถสลับไปใช้ค่าเริ่มต้นใหม่ได้หนึ่งต่อหนึ่ง

ในการดำเนินการตั้งค่าเริ่มต้นของเฟรมเวิร์กใหม่ ให้สร้างการกำหนดค่าโดยเพิ่ม accessor บนเฟรมเวิร์กเป้าหมาย ตั้งค่าค่าเริ่มต้นเป็นพฤติกรรมที่มีอยู่เพื่อให้แน่ใจว่าไม่มีอะไรเสียหายระหว่างการอัปเกรด

module ActiveJob
  mattr_accessor :existing_behavior, default: true
end

การกำหนดค่าใหม่ช่วยให้คุณสามารถดำเนินการในพฤติกรรมใหม่ได้ตามเงื่อนไข: ruby 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_7_1.rb.tt

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

เป็นขั้นตอนสุดท้ายให้เพิ่มการกำหนดค่าใหม่ในเอกสารคู่มือการกำหนดค่าใน configuration.md:

#### `config.active_job.existing_behavior

| เริ่มต้นตั้งแต่เวอร์ชัน | ค่าเริ่มต้นคือ |
| --------------------- | -------------------- |
| (เดิม)            | `true`               |
| 7.1                   | `false`              |

4.12 การละเว้นไฟล์ที่สร้างขึ้นโดยตัวแก้ไข / IDE ของคุณ

บางตัวแก้ไขและ IDE จะสร้างไฟล์หรือโฟลเดอร์ที่ซ่อนอยู่ภายในโฟลเดอร์ rails แทนที่จะยกเว้นไฟล์เหล่านั้นจากแต่ละครั้งที่ commit หรือเพิ่มไฟล์เหล่านั้นใน .gitignore ของ Rails คุณควรเพิ่มไฟล์เหล่านั้นใน ไฟล์ gitignore ส่วนตัวของคุณ.

4.13 การอัปเดต Gemfile.lock

บางการเปลี่ยนแปลงต้องการอัปเกรดขึ้นรุ่นของ dependency ในกรณีเช่นนี้ ตรวจสอบให้แน่ใจว่าคุณรัน bundle update เพื่อรับเวอร์ชันที่ถูกต้องของ dependency และ commit ไฟล์ Gemfile.lock ในการเปลี่ยนแปลงของคุณ.

4.14 ทำการ commit การเปลี่ยนแปลงของคุณ

เมื่อคุณพอใจกับโค้ดในคอมพิวเตอร์ของคุณ คุณจำเป็นต้อง commit การเปลี่ยนแปลงไปยัง Git:

$ git commit -a

นี่ควรเปิดตัว editor ของคุณเพื่อเขียนข้อความ commit เมื่อคุณเสร็จสิ้น บันทึก และปิดเพื่อดำเนินการต่อ.

ข้อความ commit ที่จัดรูปและอธิบายได้ดีจะเป็นประโยชน์อย่างมากต่อผู้อื่นในการเข้าใจว่าทำไมมีการเปลี่ยนแปลง ดังนั้นโปรดใช้เวลาเขียนมัน.

ข้อความ commit ที่ดีจะมีลักษณะดังนี้:

สรุปสั้น (อย่างไรก็ตาม ไม่เกิน 50 ตัวอักษร)

คำอธิบายที่ละเอียดมากขึ้น หากจำเป็น แต่ละบรรทัดควรขึ้นบรรทัดใหม่ที่ 72 ตัวอักษร พยายามเป็นคำอธิบายให้ละเอียดที่สุด แม้ว่าคุณคิดว่าเนื้อหาของการ commit นั้นเป็นเรื่องที่เข้าใจง่าย แต่อาจจะไม่เป็นเรื่องที่เข้าใจง่ายสำหรับผู้อื่น ให้เพิ่มคำอธิบายที่มีอยู่แล้วในปัญหาที่เกี่ยวข้อง ไม่จำเป็นต้องเข้าชมหน้าเว็บเพื่อตรวจสอบประวัติ

ส่วนคำอธิบายสามารถมีหลายย่อหน้าได้

ตัวอย่างโค้ดสามารถฝังได้โดยการเพิ่มช่องว่าง 4 ช่อง:

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

คุณยังสามารถเพิ่มข้อความย่อหน้าได้:

- สร้างข้อความย่อหน้าโดยเริ่มบรรทัดด้วยขีด (-) หรือดอกจัน (*)
- ขึ้นบรรทัดใหม่ที่ 72 ตัวอักษร และเพิ่มช่องว่าง 2 ช่องสำหรับความอ่านง่าย

เคล็ดลับ. โปรด squash การ commit ของคุณเป็นการ commit เดียวเมื่อเหมาะสม นี้จะทำให้การ cherry pick ในอนาคตง่ายขึ้นและทำให้ git log สะอาด.

4.15 อัปเดต Branch ของคุณ

มีโอกาสที่การเปลี่ยนแปลงอื่น ๆ ใน main อาจเกิดขึ้นในขณะที่คุณกำลังทำงาน ในการรับการเปลี่ยนแปลงใหม่ใน main:

$ git checkout main
$ git pull --rebase

ตอนนี้ให้นำแพทช์ของคุณมาใช้บนการเปลี่ยนแปลงล่าสุด:

$ git checkout my_new_branch
$ git rebase main

ไม่มีความขัดแย้งหรือไม่? ทดสอบยังผ่านไหม? การเปลี่ยนแปลงยังคงดูเหมาะสมต่อคุณหรือไม่? แล้วทำการ push การเปลี่ยนแปลงที่ถูก rebase ไปยัง GitHub: bash $ git push --force-with-lease

เราไม่อนุญาตให้ใช้ force push ในเบสของเรา (rails/rails) แต่คุณสามารถ force push ไปยัง fork ของคุณได้ การ rebase จำเป็นต้องใช้ force push เนื่องจากประวัติการเปลี่ยนแปลง

4.16 Fork

ไปที่เรื่อง GitHub repository ของ Rails และกด "Fork" ที่มุมบนขวาของหน้าจอ

เพิ่ม remote ใหม่ใน local repository บนเครื่องคอมพิวเตอร์ของคุณ:

$ git remote add fork https://github.com/<ชื่อผู้ใช้ของคุณ>/rails.git

คุณอาจจะได้ทำการ clone local repository ของคุณจาก rails/rails หรืออาจจะได้ทำการ clone จาก forked repository ของคุณ คำสั่ง git ต่อไปนี้ถือว่าคุณได้สร้าง remote "rails" ที่ชี้ไปที่ rails/rails

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

ดาวน์โหลด commits และ branches ใหม่จาก official repository:

$ git fetch 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

4.17 เปิด Pull Request

ไปที่ repository ของ Rails ที่คุณเพิ่ง push (เช่น https://github.com/your-user-name/rails) และคลิกที่ "Pull Requests" ที่แถบด้านบน (เหนือโค้ด) ในหน้าถัดไป คลิกที่ "New pull request" ที่มุมบนขวาของหน้าจอ

Pull request ควรจะเป้าหมายที่เบส repository rails/rails และ branch main เบส repository จะเป็นงานของคุณ (your-user-name/rails) และ branch จะเป็นชื่อที่คุณตั้งให้กับ branch ของคุณ คลิก "create pull request" เมื่อคุณพร้อมแล้ว

ตรวจสอบว่าคุณได้รวม changesets ที่คุณนำเสนอแล้ว กรอกข้อมูลเพิ่มเติมเกี่ยวกับ patch ที่คุณต้องการ โดยใช้เทมเพลต pull request ที่ให้ไว้ เมื่อเสร็จสิ้น คลิก "Create pull request"

4.18 รับคำแนะนำ

ส่วนใหญ่ pull request จะผ่านการแก้ไขหลายรอบก่อนที่จะถูกผสานเข้ากับโครงการ ผู้ร่วมงานคนต่าง ๆ อาจมีความคิดเห็นที่แตกต่างกัน และบางครั้ง patches อาจต้องได้รับการแก้ไขก่อนที่จะสามารถผสานเข้ากับโครงการได้

บางคนใน Rails อาจมีการแจ้งเตือนทางอีเมลจาก GitHub เปิดอยู่ แต่บางคนไม่ได้เปิด นอกจากนี้ (เกือบ) ทุกคนที่ทำงานใน Rails เป็น อาสาสมัคร ดังนั้นอาจใช้เวลาสักหลายวันก่อนที่คุณจะได้รับคำแนะนำครั้งแรกเกี่ยวกับ pull request อย่าหงุดหงิด! บางครั้งมันเร็ว บางครั้งมันช้า นั่นคือชีวิตของโอเพนซอร์ส

หากผ่านไปเกินหนึ่งสัปดาห์แล้ว และคุณยังไม่ได้ยินอะไร คุณอาจต้องพยายามกระตุ้นเรื่องนี้ คุณสามารถใช้ rubyonrails-core discussion board สำหรับเรื่องนี้ คุณยังสามารถ แสดงความคิดเห็นอีกครั้งใน pull request

ในขณะที่คุณกำลังรอคำแนะนำเกี่ยวกับ pull request ของคุณ ลองเปิด pull request อื่น ๆ อีกหลายรายการและให้คนอื่น ๆ บางคนดู! พวกเขาจะขอบคุณเช่นเดียวกับที่คุณขอบคุณคำแนะนำเกี่ยวกับ patches ของคุณ

โปรดทราบว่าเฉพาะทีม Core และ Committers เท่านั้นที่ได้รับอนุญาตให้ผสานการเปลี่ยนแปลงของโค้ด หากมีคนให้คำแนะนำและ "อนุมัติ" การเปลี่ยนแปลงของคุณ อาจจะไม่มีความสามารถ หรือมีสิทธิ์สุดท้ายในการผสานการเปลี่ยนแปลงของคุณ

4.19 ทำซ้ำตามความจำเป็น

มีโอกาสที่คำแนะนำที่คุณได้รับจะแนะนำให้ทำการเปลี่ยนแปลง อย่าเสียใจ: จุดประสงค์หลักในการมีส่วนร่วมในโครงการโอเพนซอร์สที่เป็นกิจกรรมคือการใช้ความรู้ของชุมชน หากมีคนสนับสนุนให้คุณปรับปรุงโค้ดของคุณ คุณควรทำการปรับปรุงและส่งใหม่ หากคำแนะนำว่าโค้ดของคุณไม่สามารถผสานเข้ากับโครงการได้ คุณอาจยังคิดที่จะเผยแพร่เป็น gem

4.19.1 การรวม Commit

หนึ่งในสิ่งที่เราอาจขอให้คุณทำคือ "การรวม commit" ซึ่งจะรวม commit ทั้งหมดของคุณเข้าไปใน commit เดียว พวกเราชอบ pull request ที่เป็น commit เดียว เพราะจะทำให้ง่ายต่อการย้อนกลับไปยัง branch ที่เสถียร การรวม commit จะทำให้ง่ายต่อการยกเลิก commit ที่ผิดพลาด และประวัติของ git จะง่ายต่อการติดตาม โครงการ Rails เป็นโครงการที่ใหญ่ และ commit ที่ไม่เกี่ยวข้องอาจเพิ่มเสียงรบกวนได้มาก

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

< เลือก 'squash' สำหรับ commit ทั้งหมดยกเว้น commit แรก >
< แก้ไขข้อความ commit เพื่อให้มีความหมายและอธิบายการเปลี่ยนแปลงทั้งหมดของคุณ >

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

คุณควรสามารถรีเฟรช pull request บน GitHub และเห็นว่ามีการอัปเดตแล้ว

4.19.2 การอัปเดต Pull Request

บางครั้งคุณอาจถูกขอให้ทำการเปลี่ยนแปลงบางอย่างในโค้ดที่คุณได้ commit ไว้แล้ว สิ่งนี้อาจรวมถึงการแก้ไข commit ที่มีอยู่ ในกรณีนี้ Git จะไม่อนุญาตให้คุณ push การเปลี่ยนแปลงเนื่องจากการ push branch และ local branch ไม่ตรงกัน แทนที่จะเปิด pull request ใหม่ คุณสามารถ force push ไปยัง branch ของคุณบน GitHub ได้ตามที่ได้กล่าวไว้ในส่วนการรวม commit:

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

สิ่งนี้จะอัปเดต branch และ pull request บน GitHub ด้วยโค้ดใหม่ของคุณ โดยการ force push ด้วย --force-with-lease git จะอัปเดต remote อย่างปลอดภัยกว่าด้วย -f ที่มักจะลบงานจาก remote ที่คุณยังไม่มี

4.20 เวอร์ชันเก่าของ Ruby on Rails

หากคุณต้องการเพิ่มการแก้ไขในเวอร์ชันของ Ruby on Rails ที่เก่ากว่าเวอร์ชันถัดไป คุณจะต้องตั้งค่าและสลับไปยัง local tracking branch ของคุณเอง นี่คือตัวอย่างในการสลับไปยัง branch 7-0-stable:

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

หมายเหตุ: ก่อนที่จะทำงานในเวอร์ชันเก่า ๆ โปรดตรวจสอบ นโยบายการบำรุงรักษา การเปลี่ยนแปลงจะไม่ได้รับการยอมรับในเวอร์ชันที่เข้าสู่ช่วงปลายชีวิต

4.20.1 การย้อนกลับ

การเปลี่ยนแปลงที่ถูกผสานเข้ากับ main จะถูกตั้งใจสำหรับเวอร์ชันหลักถัดไปของ Rails บางครั้งอาจจะเป็นประโยชน์ที่จะแพร่กระจายการเปลี่ยนแปลงของคุณกลับไปยัง stable branches เพื่อรวมไว้ในการอัปเดตการบำรุงรักษา โดยทั่วไป การแก้ไขความปลอดภัยและการแก้ไขข้อผิดพลาดเป็นตัวเลือกที่ดีสำหรับการย้อนกลับ ในขณะที่คุณสร้างความสงสัย การปรึกษาสมาชิกทีม Rails จะเป็นที่ดีกว่าก่อนที่จะย้อนกลับการเปลี่ยนแปลงของคุณเพื่อหลีกเลี่ยงความพยายามที่เปลืองเวลา

ก่อนอื่น ตรวจสอบให้แน่ใจว่า main branch ของคุณเป็นเวอร์ชันล่าสุด

$ git checkout main
$ git pull --rebase

เช็คเอาท์ branch ที่คุณกำลังย้อนกลับไป เช่น 7-0-stable และตรวจสอบให้แน่ใจว่าเป็นเวอร์ชันล่าสุด:

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

หากคุณกำลังย้อนกลับ pull request ที่ผ่านการผสาน ค้นหา commit สำหรับการผสานและ cherry-pick มัน: bash $ git cherry-pick -m1 MERGE_SHA

แก้ไขความขัดแย้งที่เกิดขึ้นในการ cherry-pick แล้วกด push การเปลี่ยนแปลงของคุณ จากนั้นเปิด PR ที่ชี้ไปที่แขนงที่คุณกำลังทำการ backport ถ้าคุณมีการเปลี่ยนแปลงที่ซับซ้อนมากขึ้น คู่มือ cherry-pick สามารถช่วยได้

5 ผู้มีส่วนร่วมใน Rails

การมีส่วนร่วมทั้งหมดจะได้รับเครดิตใน ผู้มีส่วนร่วมใน Rails

ข้อเสนอแนะ

คุณสามารถช่วยปรับปรุงคุณภาพของคู่มือนี้ได้

กรุณาช่วยเพิ่มเติมหากพบข้อผิดพลาดหรือข้อผิดพลาดทางความจริง เพื่อเริ่มต้นคุณสามารถอ่านส่วน การสนับสนุนเอกสาร ของเราได้

คุณอาจพบเนื้อหาที่ไม่สมบูรณ์หรือเนื้อหาที่ไม่ได้อัปเดต กรุณาเพิ่มเอกสารที่ขาดหายไปสำหรับเนื้อหาหลัก โปรดตรวจสอบ Edge Guides ก่อนเพื่อตรวจสอบ ว่าปัญหาได้รับการแก้ไขหรือไม่ในสาขาหลัก ตรวจสอบ คู่มือแนวทาง Ruby on Rails เพื่อดูรูปแบบและกฎเกณฑ์

หากคุณพบข้อผิดพลาดแต่ไม่สามารถแก้ไขได้เอง กรุณา เปิดปัญหา.

และสุดท้าย การสนทนาใด ๆ เกี่ยวกับ Ruby on Rails เอกสารยินดีต้อนรับที่สุดใน เว็บบอร์ดอย่างเป็นทางการของ Ruby on Rails.