แปลโดย : Claude 3.7 Sonnet / source : https://jonatack.github.io/articles/how-to-review-pull-requests-in-bitcoin-core
Last updated
คู่มือนี้สร้างขึ้นบนพื้นฐานที่วางไว้โดยการนำเสนอเหล่านี้:
A Gentle Introduction to Bitcoin Core Development โดย Jimmy Song (2017)
Contributing to Bitcoin Core, a Personal Account โดย John Newbery (2017)
Understanding the Technical Side of Bitcoin โดย Pierre Rochard (2018)
/ / โดย Jeremy Rubin (2018)
การทบทวนและการทดสอบอาจเป็นวิธีที่ดีที่สุดในการเริ่มมีส่วนร่วมใน Bitcoin Core
ประสบการณ์การทบทวนและการทดสอบเป็นสิ่งที่นักพัฒนา Bitcoin Core ระยะยาวอ้างถึงเป็นประจำว่าเป็นทั้ง:
คอขวดของทรัพยากร (resource bottlenecks) และ
วิธีที่ดีที่สุดและเป็นประโยชน์มากที่สุดในการเรียนรู้และเริ่มมีส่วนร่วมและสร้างชื่อเสียงในชุมชน
Nit: ปัญหาเล็กน้อย มักไม่เป็นอุปสรรคต่อการทำงาน
PR: คำย่อของ pull request บางครั้งเรียกว่า merge request เป็นการเสนอการเปลี่ยนแปลงโค้ดหรือเอกสารในแหล่งที่เก็บซอร์สโค้ด
WIP: คำย่อของ work in progress (งานที่อยู่ระหว่างดำเนินการ)
ในฐานะผู้มาใหม่ เป้าหมายคือการพยายามเพิ่มคุณค่า ด้วยความเป็นมิตรและความถ่อมตัว ในขณะที่เรียนรู้ให้มากที่สุดเท่าที่จะเป็นไปได้ (ไม่เฉพาะในฐานะผู้มาใหม่เท่านั้น กระบวนการนี้ไม่มีวันสิ้นสุด)
วิธีการที่ดีคือการทำให้ไม่ใช่เรื่องของคุณ แต่เป็น "ฉันจะทำให้ดีที่สุดได้อย่างไร?"
หนึ่งในความท้าทายที่ยากที่สุดที่ผู้มีส่วนร่วมใหม่ต้องเผชิญคือความกว้างของโค้ดเบสและความซับซ้อนของเทคโนโลยีที่ล้อมรอบมัน
ให้ตระหนักถึงสิ่งที่คุณไม่รู้; ผู้มีส่วนร่วมในระยะยาวมีประสบการณ์และบริบทหลายปี ชุมชนได้สร้างความรู้และประสบการณ์ร่วมกันอย่างลึกซึ้ง โปรดจำไว้ว่าความคิดใหม่ของคุณอาจถูกเสนอหรือพิจารณามาหลายครั้งแล้วในอดีต
จำไว้ว่าทรัพยากรของผู้มีส่วนร่วมและผู้ดูแลมีจำกัด — ขอใช้อย่างระมัดระวังและเคารพ เป้าหมายคือพยายามให้มากกว่าที่คุณรับ ช่วยเหลือมากกว่าขัดขวาง ในขณะที่กำลังเรียนรู้
พยายามค้นหาสิ่งต่างๆ ด้วยตัวเอง อย่างน้อยก็เพียงพอที่จะเคารพเวลาของผู้อื่น
ติดตามช่อง IRC #bitcoin-core-dev และเมลลิ่งลิสต์ bitcoin-dev
ช่อง IRC เพิ่มเติมที่ควรติดตามสามารถพบได้ ที่นี่
ก่อนที่จะเข้าร่วม ใช้เวลาให้มากพอเพื่อ:
เข้าใจกระบวนการและแนวทางการมีส่วนร่วม ไม่เพียงแต่โดยการอ่านเอกสารในที่เก็บ โดยเฉพาะอย่างยิ่ง Contributing Guide, Developer Notes และ Productivity Notes (และโดยทั่วไป ทุกอย่างในไดเรกทอรี doc และ test) แต่ยังโดยการสังเกตการโต้ตอบบนช่อง IRC #bitcoin-core-dev และการทบทวนโค้ดที่กำลังดำเนินอยู่ในที่เก็บ
รู้จักผู้มีส่วนร่วมประจำ: พวกเขาทำอะไร พวกเขาชอบและต้องการอะไร พวกเขาให้ข้อเสนอแนะอย่างไร
ผู้มาใหม่หลายคนเริ่มต้นด้วยการเปิด pull requests ที่เพิ่มเข้าไปในหลายร้อยรายการที่รอการทบทวนที่มีคุณค่า จะดีกว่าถ้าเริ่มต้นด้วยการทบทวน pull requests ที่มีอยู่และเริ่มทำความเข้าใจว่า pull requests และการทบทวนประเภทใดที่เป็นประโยชน์มากที่สุด ในขณะที่ค่อยๆ ได้รับภาพรวม
กฎทั่วไปที่ดีคือทบทวน PR 5-15 รายการสำหรับแต่ละ PR ที่คุณเปิด
ภาพรวมสำคัญกว่าข้อบกพร่องเล็กน้อย การสะกดคำ หรือรูปแบบโค้ด
มีระดับการทบทวนภาพรวมที่แตกต่างกัน: "การเปลี่ยนแปลงนี้ส่งผลต่อพฤติกรรมหรือไม่?" หรือ "นี่ปลอดภัยหรือไม่?" แตกต่างจาก "นี่เป็นความคิดที่ดีหรือไม่?" อย่างหลังอาจต้องการบริบทมากขึ้น ซึ่งคุณจะค่อยๆ ได้รับเมื่อเวลาผ่านไป อย่าให้สิ่งนั้นหยุดคุณจากการคิดเกี่ยวกับคำถามเหล่านี้และพยายามทบทวนในระดับนั้น
ขั้นตอนในการปรับปรุงความเข้าใจของภาพรวม:
ทำตามคู่มือการศึกษาของ Chaincode Labs
พิจารณาสมัครและเข้าร่วมสัมมนาออนไลน์ของ Chaincode Labs ซึ่งได้รับการแนะนำอย่างสูง (ที่ยังทำหน้าที่เป็นการค้นหาบุคลากรที่มีความสามารถสำหรับนักพัฒนาใหม่ที่กำลังมองหางานเกี่ยวกับ Bitcoin และเงินทุนโอเพนซอร์ส)
ศึกษา Bitcoin Improvement Proposals (มักถูกอ้างถึงในรูปแบบเอกพจน์โดยใช้คำย่อว่า "BIP") และกลับมาดูบ่อยๆ
สมัครรับจดหมายข่าว Bitcoin Optech และใช้หน้าหัวข้อของพวกเขาเป็นแหล่งข้อมูลหลัก
ทำ Learning Bitcoin from the Command Line
มุ่งเน้นคุณภาพมากกว่าปริมาณและสมดุลระหว่างงานเชิงลึกและชัยชนะที่รวดเร็ว
เอกสารมีความสำคัญ เช่น เอกสารระดับสูงเกี่ยวกับวิธีการทำงานและการโต้ตอบ เอกสารโค้ดที่ชัดเจนและถูกต้อง ฟังก์ชันมีคำอธิบายที่ดีและเอกสาร Doxygen หรือไม่ การบันทึกการทดสอบ (ทั้งข้อมูลและการดีบัก) และอื่นๆ
ความครอบคลุมของการทดสอบมีความสำคัญ อย่าลังเลที่จะปรับปรุงหรือเขียนการทดสอบหน่วย (unit test) การทดสอบการทำงาน (functional test) หรือการทดสอบ fuzz ที่ขาดหายไป
เป็นผู้มีส่วนร่วมที่ถ่อมตัวและมีน้ำใจ ช่วยให้ PR เดินหน้าโดยการทบทวน เสนอการทดสอบหรือการแก้ไขในวิธีที่เป็นประโยชน์ เสนอที่จะ rebase หรือแม้กระทั่งเสนอที่จะรับช่วงต่อ PR หลังจากเงียบไปหลายเดือน โดยสรุป ช่วยเหลือซึ่งกันและกัน!
พยายามหลีกเลี่ยงการแสดงความคิดเห็นมากเกินไปใน PR เกี่ยวกับข้อบกพร่องเล็กน้อย (nits) รายละเอียดปลีกย่อย และรูปแบบโค้ด โดยเฉพาะอย่างยิ่งกับ PR ที่ติดป้าย WIP หรือเมื่อ PR เพิ่งถูกยื่นและผู้เขียน PR กำลังมองหา Concept ACKs และ Approach ACKs เป็นหลัก เช่น ความเห็นชอบทั่วไป ไม่ใช่การจับผิดเล็กๆ น้อยๆ
ผู้มีส่วนร่วมระยะยาวรายงานว่ากิจกรรมเช่นนี้ทำให้พวกเขาไม่พอใจ และอาจลดทุนทางสังคมของคุณในโครงการ พยายามเข้าใจว่าต้องการการทบทวนแบบใดและเมื่อใดควรทำอะไร
เวลาที่ดีที่สุดสำหรับการแสดงความคิดเห็นเกี่ยวกับข้อบกพร่องเล็กน้อยคือหลังจาก Concept/Approach ACKs และฉันทามติเกี่ยวกับ PR และก่อนที่ PR จะเสร็จสมบูรณ์และมี tested ACKs ตามที่ Pieter Wuille เขียนใน IRC: "ผมคิดว่าสิ่งที่รบกวน PR มากที่สุดคือการได้รับความคิดเห็นเกี่ยวกับระดับต่ำ/nits/รูปแบบโค้ดจำนวนมาก ในขณะที่ยังไม่ชัดเจนว่า PR นั้นเป็นที่ต้องการในแง่แนวคิดหรือไม่"
ให้คำแนะนำเกี่ยวกับข้อบกพร่องเล็กน้อยและรูปแบบในลักษณะที่เป็นมิตร เบาๆ และเอื้ออำนวย — เช่น รู้สึกอิสระที่จะเพิกเฉย รู้สึกอิสระที่จะปรับหากคุณบังเอิญ rebase เป็นต้น
โปรดจำไว้ว่าไม่มีใครถูกบังคับให้นำความคิดเห็นในการทบทวนของคุณมาพิจารณา ผู้เขียนสามารถตอบได้ว่าพวกเขาไม่ต้องการทำบางสิ่งหากพวกเขารู้สึกว่าอยู่นอกขอบเขตของการเปลี่ยนแปลง โดยเฉพาะอย่างยิ่งหากความคิดเห็นของคุณเป็นการจับผิดเล็กๆ น้อยๆ
เมื่อคุณสามารถทำได้ ให้เพิ่มระดับความยากและความสำคัญของ PR ที่คุณทบทวน
คุณภาพของการทบทวนสำคัญกว่าปริมาณมาก คุณสามารถเพิ่มคุณค่าและเรียนรู้มากขึ้นโดยใช้เวลาทำการทบทวนเชิงลึกที่มีคุณภาพของ PR ที่มีความสำคัญสูงและ PR ที่ยากขึ้น PR เหล่านี้มักทำให้ผู้คนรู้สึกหวาดกลัวและอาจซบเซาเป็นเดือนๆ ทำลายแรงจูงใจของผู้เขียนด้วยการตายจากแผลพันบาดแผลเนื่องจากขาดการทบทวนที่มีคุณภาพ การจับผิดเล็กๆ น้อยๆ/การถกเถียงเรื่องรูปแบบโค้ด (bikeshedding) และนรก rebase การทบทวนพวกเขาอย่างดีเป็นการให้บริการที่แท้จริงแก่ Bitcoin
กระบวนการยกระดับต้องใช้เวลา ไม่มีอะไรสามารถทดแทนเดือนและปีที่ลงทุนในการรวบรวมบริบทและความเข้าใจจากการติดตามโค้ด ปัญหา pull requests ช่อง IRC #bitcoin-core-dev และเมลลิ่งลิสต์ bitcoin-dev
คำถามแรกที่มีประโยชน์เมื่อเริ่มการทบทวนคือ "อะไรที่จำเป็นที่สุดที่นี่ในขณะนี้?" การตอบคำถามนี้ต้องอาศัยประสบการณ์และบริบทที่สะสมมา แต่เป็นคำถามที่มีประโยชน์ในการตัดสินใจว่าคุณจะเพิ่มคุณค่าให้มากที่สุดในเวลาน้อยที่สุดได้อย่างไร ขึ้นอยู่กับว่าการเปลี่ยนแปลงมีความซับซ้อนหรือสำคัญแค่ไหนและ PR อยู่ในกระบวนการทบทวนมากแค่ไหน การทบทวนที่มีประสบการณ์ที่เป็นประโยชน์อาจเกี่ยวข้องกับการอ่านโค้ดอย่างคร่าวๆ และการใช้บริบทมากมายกับความคิดเห็นโค้ดที่เกี่ยวข้องในสถานที่สำคัญมากกว่าการทำการทบทวนเต็มรูปแบบที่เกี่ยวข้องกับการ debug-building การทดสอบ และการทบทวนแต่ละ commit อย่างไรก็ตาม ในกรณีส่วนใหญ่ การทำการทบทวนเต็มรูปแบบที่เหมาะสมจะดีที่สุดและเพิ่มคุณค่ามากที่สุด
รักษาอีโก้และความหวังออกจากกระบวนการ อย่าเอาเรื่องส่วนตัวและเดินหน้าต่อไป
เมื่อมีข้อสงสัย ให้สันนิษฐานว่ามีเจตนาดี
อดทนกับผู้คนและผลลัพธ์
ชื่นชมในที่สาธารณะ วิจารณ์ในที่ส่วนตัวและในลักษณะที่ให้กำลังใจ
ความพยายามช่วย ทำงานกับมันทุกวัน
สิ่งเหล่านี้ทั้งหมดพูดง่ายกว่าทำ มีความเห็นอกเห็นใจกับตัวเองและผู้อื่น
จำไว้ว่าต้องทบทวน PR 5-15 รายการ (หรือจัดการหรือทดสอบปัญหา 5-15 รายการ) สำหรับทุก PR ที่คุณเปิด
สุดท้าย ตรวจสอบให้แน่ใจว่าคุณทบทวนการมีส่วนร่วมจากผู้คนที่หลากหลายและระดับประสบการณ์ที่แตกต่างกัน ไม่ใช่เฉพาะผู้ที่อยู่ในกลุ่มเพื่อนร่วมงานหรือคนรู้จักของคุณ ติดต่อคนใหม่และคนที่แตกต่าง (ข้อความ IRC โดยตรงใช้ได้ดี) เพื่อถามว่าคุณจะช่วยพวกเขาได้อย่างไร คุณสามารถขอความช่วยเหลือได้เป็นครั้งคราวเช่นกัน แต่อย่ารู้สึกว่าคุณมีสิทธิ์ ให้ (มาก) มากกว่าที่คุณรับ
อย่าเชื่อ ให้ตรวจสอบ ลดการพึ่งพา GitHub ในกระบวนการทบทวนของคุณ ใช้เว็บไซต์ GitHub เฉพาะสำหรับ metadata ของ GitHub เท่านั้น เช่น การอ่านความคิดเห็นและเพิ่มความคิดเห็นของคุณเอง — ไม่ใช่สำหรับการทบทวน commits และโค้ด ซึ่งคุณควรทำในสภาพแวดล้อมท้องถิ่นของคุณ
ดังนั้น การทบทวนจึงเริ่มต้นด้วยการดึง PR branch ลงมาที่คอมพิวเตอร์ของคุณเพื่อสร้างและทบทวนในเครื่อง มีวิธีที่แตกต่างกันในการทำเช่นนี้ขึ้นอยู่กับสิ่งที่คุณต้องการ ความต้องการของคุณ พื้นที่ดิสก์ แบนด์วิดท์อินเทอร์เน็ต ฯลฯ นี่คือบางวิธี:
การดึง remote PRs ด้วย git checkout pr/<number> ตามที่อธิบายใน gist เล็กๆ น่ารักนี้ซึ่งสามารถปรับเปลี่ยนให้เหมาะกับความต้องการของคุณ
ส่วน [remote "origin"] ใน gitconfig ของฉัน: fetch = +refs/pull/*/head:refs/remotes/origin/pr/*
เวอร์ชันของ Luke Dashjr ผู้มีส่วนร่วมใน Bitcoin Core: "เพื่อหลีกเลี่ยง merge branches ทั้งหมด ให้กำหนดค่า origin-pull remote เป็น": fetch = +refs/pull/*/head:refs/remotes/origin-pull/*/head
เอกสาร Bitcoin Core สำหรับการอ้างอิง PRs อย่างง่ายด้วย refspecs
GitHub แสดง PRs เป็น branches บน upstream repository ด้วย pull/<number>/head (contributor branch) และ pull/<number>/merge (merged into master) เช่น git fetch origin pull/17283/head && git checkout FETCH_HEAD อย่างไรก็ตาม ฉันชอบพึ่งพา GitHub ให้น้อยที่สุดเท่าที่จะเป็นไปได้
คุณสามารถทดสอบ PR ได้ทั้งบน contributor's branch หรือด้วยการเปลี่ยนแปลงที่ merge ไว้ด้านบนของ master การทดสอบแบบหลังสามารถมีประโยชน์เพื่อดูว่ามีอะไรที่ merge เข้ากับ master ตั้งแต่ commit PR ล่าสุดที่ทำให้การเปลี่ยนแปลงเสียหายหรือไม่
ต่อไป เริ่มการสร้างและการทดสอบในขณะที่คุณเริ่มอ่านโค้ดในเครื่อง คุณต้องทำตัวให้คุ้นเคยกับการคอมไพล์ Bitcoin Core จากซอร์สและการเรียกใช้ unit tests และ functional tests เนื่องจากคุณจะต้องทำเช่นนี้สำหรับ PRs จำนวนมากที่คุณทดสอบ สำหรับเรื่องนี้ Bitcoin Core productivity notes เป็นสิ่งที่ขาดไม่ได้
อ่านและรู้จัก Bitcoin Core developer notes
ในขณะที่การสร้างและการทดสอบกำลังทำงาน เริ่มทบทวนแต่ละ commit แยกกันในสภาพแวดล้อมท้องถิ่นของคุณโดยใช้เครื่องมือเปรียบเทียบเช่น gitk, meld, meld สำหรับ macOS, GNU ediff สำหรับ Emacs, vimdiff หรือ vim-diffconflicts สำหรับ Vim, opendiff บน macOS, หรือ diffoscope (นี่คือเคล็ดลับการใช้งาน diffoscope บางประการ)
ถ้าคุณใช้ gitk และชอบโหมดมืด ฉันแนะนำ Dracula สำหรับ gitk
ฝึกฝนการค้นหาในที่เก็บด้วย git grep คุณจะใช้มันอย่างต่อเนื่องเพื่อค้นหาสิ่งต่างๆ ในโค้ดเบส รัน git grep --help บน command line เพื่อขอความช่วยเหลือหรือข้อมูล
อ่านโค้ด อ่านความคิดเห็น PR แล้วอ่านซ้ำทั้งสอง ค้นหาบางสิ่งที่ไม่มีความหมายและพยายามหาคำตอบ ทำซ้ำ
เมื่อทุกอย่างเริ่มมีความหมาย ให้เรียกใช้ bitcoind บน regtest, testnet (หรือบน mainnet ด้วยจำนวนเล็กน้อย) และดูหรือค้นหาผ่านบันทึกที่เกี่ยวข้อง (รัน bitcoin-cli help logging สำหรับหมวดหมู่การบันทึกของ bitcoind ต่างๆ และวิธีการสลับเปิด/ปิด)
อาจเพิ่มการบันทึกแบบกำหนดเอง LogPrintfs หรือ asserts; มันเป็นเอกสิทธิ์เสมอที่จะเพิ่มสิ่งเหล่านี้ลงในโค้ดของคนอื่น (เพื่อดูวิธีการ ให้รัน git grep -ni logprintf หรือ git grep assert ในที่เก็บ)
เรียกใช้การทดสอบการทำงานที่เกี่ยวข้องและดูผ่านบันทึกการดีบัก ตรวจสอบว่าพวกมันล้มเหลวในลักษณะที่คาดไว้บน master กลับไปที่ PR branch กลับด้านหรือเปลี่ยนการทดสอบใหม่เพื่อให้พวกมันแตกและเข้าใจว่าทำไม
อาจเพิ่มจุดหยุด C++ gdb หรือ Python pdb (หรือเพิ่ม import pdb; pdb.set_trace() ที่ใดก็ได้ในโค้ดการทดสอบการทำงาน) ตรวจสอบค่า เรียกใช้คำสั่ง RPC
ตรวจสอบว่ามีการมองข้าม call sites, headers หรือ declarations ใน PR หรือไม่
ลองปรับโครงสร้างโค้ดให้ดีขึ้นหรือสวยงามขึ้น และค้นพบว่าทำไมมันไม่ทำงาน คาดว่ามันจะใช้เวลานานกว่าที่คุณวางแผนไว้สองเท่า ใช่ มันเป็นงาน
อาจเรียกใช้ strace (man page strace) เพื่อติดตาม system calls และ signals
ขึ้นอยู่กับการเปลี่ยนแปลง การมีส่วนร่วมของ benchmarks, memory profiling/valgrind หรือ flame graphs ในการทบทวน PR บางครั้งอาจเป็นประโยชน์อย่างมาก และแม้กระทั่งเป็นตัวตัดสิน
ฉันรักษาเอกสารบันทึกทางเทคนิคต่างๆ สำหรับตัวเอง ซึ่งฉันอ้างถึงบ่อยเมื่อทำงานกับ Bitcoin Core ที่นี่: jonatack/bitcoin-development/notes.txt นอกจากนี้ยังมีสิ่งที่เป็นประโยชน์ในที่เก็บที่บันทึกเหล่านั้นตั้งอยู่ อีกที่เก็บแหล่งข้อมูลที่ยอดเยี่ยมคือ fanquake/core-review
สอง gists ที่ดีเกี่ยวกับการดีบัก Bitcoin Core:
Debugging Bitcoin Core โดย Fabian Jahr
Hack and Debug Bitcoin Core with GDB or LLDB โดย Angel Leon
ในขณะที่คุณกำลังทบทวน การเขียนการทดสอบด้วยตัวเองสามารถช่วยให้คุณเข้าใจพฤติกรรมและตรวจสอบการเปลี่ยนแปลง และหากพวกมันเพิ่มความครอบคลุมที่เป็นประโยชน์ คุณสามารถเสนอพวกมันให้กับผู้เขียนเพื่อรวมเข้าใน PR การเสนอการทดสอบอัตโนมัติเป็นวิธีที่เป็นประโยชน์จริงๆ ในการเริ่มมีส่วนร่วม ผู้เขียนชื่นชมเมื่อมีคนทบทวน PR ของพวกเขาและให้การทดสอบเพิ่มเติม นี่คือตัวอย่าง
จำไว้ว่า ภาพรวมสำคัญกว่ามาก nits, การสะกดคำ หรือรูปแบบโค้ด อ่านส่วน Nits ด้านบนอีกครั้ง พยายามหลีกเลี่ยงการแสดงความคิดเห็นเกี่ยวกับสิ่งเหล่านี้ในขณะที่ทบทวน แม้ว่าคุณจะไม่มีความคิดเห็นอื่นๆ ที่จะให้ ฉันรู้ มันยาก — ฉันทำมันหลายครั้งเกินไป — แต่มีทางเลือกที่ดีกว่า:
สิ่งที่ดีที่คุณสามารถทำในฐานะผู้ทบทวนโดยไม่มีความรู้เฉพาะทางเกี่ยวกับโค้ดคือการถามคำถาม ผู้เขียน PR มักมีความสุขที่จะพูดคุยเกี่ยวกับงานของพวกเขาหรือเห็นความสนใจในมัน ดังนั้น ใช้เวลาประมาณ 20 นาทีในการดูการเปลี่ยนแปลง หาสิ่งที่ดูเหมือนจะสับสนหรือน่าประหลาดใจมากที่สุด และถามเกี่ยวกับมันอย่างสุภาพในความคิดเห็น PR หรือบนช่อง IRC #bitcoin-core-dev โอกาสที่คนอื่นสงสัยเกี่ยวกับสิ่งเดียวกันและมันสามารถอธิบายหรือจัดทำเอกสารได้ดีขึ้น ในทางนี้คุณสามารถเรียนรู้และช่วยทำให้โครงการเข้าถึงได้มากขึ้นด้วย (เครดิตสำหรับย่อหน้านี้: Russ Yanofsky)
ตรวจสอบให้แน่ใจว่าได้เรียนรู้และเข้าใจกระบวนการตรวจสอบโดย peer ของ Bitcoin Core กระบวนการมักได้รับการอัปเดตบ่อย ดังนั้นให้อ้างอิงกลับไปบ่อยๆ
ACK (ที่มา) โดยทั่วไปจะตามด้วยคำอธิบายว่าผู้ทบทวนทำการทบทวนและการทดสอบด้วยตนเองอย่างไร ในฐานะผู้มีส่วนร่วมใหม่ แนะนำให้ใช้คำอธิบายในความคิดเห็นการทบทวนมากขึ้นเพื่อให้บริบทเกี่ยวกับสิ่งที่คุณทำและคิดผ่านระหว่างการทบทวนและแสดงว่าคุณเข้าใจการเปลี่ยนแปลง
Concept ACK หมายความว่าผู้ทบทวนรับทราบและเห็นด้วยกับเป้าหมายของการเปลี่ยนแปลง แต่ไม่ (ยัง) ยืนยันว่าพวกเขาได้ดูโค้ดหรือทดสอบมัน นี่สามารถเป็นสัญญาณที่มีคุณค่าต่อผู้เขียน PR เพื่อให้พวกเขาทราบว่า PR มีคุณค่าและกำลังมุ่งไปในทิศทางที่ถูกต้อง เป็นผลโดยตรง Concept NACK จะบ่งชี้ถึงความไม่เห็นด้วยกับเป้าหมาย
Approach ACK เป็นขั้นตอนต่อไปจาก Concept ACK และหมายถึงความเห็นชอบทั้งเป้าหมายและวิธีการที่ใช้ในการดำเนินการเปลี่ยนแปลง ดังนั้น Approach NACK จะบ่งชี้ถึงความเห็นชอบกับเป้าหมายแต่ไม่ใช่วิธีการ
ผู้ทบทวนบางครั้งแสดงความคิดเห็นว่า "Code review ACK" เพื่อสื่อสารว่าโค้ดดูดี แต่พวกเขาไม่ได้ทดสอบการเปลี่ยนแปลงหรือยังไม่มีความคิดเห็นเกี่ยวกับแนวคิด เป็นการดีที่จะเพิ่มบริบทเพื่อทำให้ชัดเจน: "Code review ACK HEAD, ไม่แน่ใจเกี่ยวกับแนวคิด ฉันต้องการตรวจสอบ x, y, z, ฯลฯ"
รูปแบบ ACK อื่นๆ ที่ใช้บางครั้งคือ "tACK" หรือ "tested ACK" และ "utACK" หรือ "untested ACK"
การทดสอบด้วยตนเองของฟีเจอร์ใหม่และปัญหาที่รายงานมักได้รับการต้อนรับเสมอ ความคิดเห็นที่เป็นประโยชน์จริงๆ ในการทบทวน: "นี่คือสิ่งที่ฉันทดสอบและวิธีการของฉัน" โดยเฉพาะอย่างยิ่งเพื่อสนับสนุน ACK
บาง PRs อาจยากที่จะทดสอบหรือ ACK เนื่องจากความซับซ้อน บริบท หรืออาจเป็นการขาดการทดสอบหรือกรอบการจำลอง นั่นไม่ควรทำให้คุณท้อใจจากการทบทวน ตัวอย่างเช่น หากคุณได้ทบทวนโค้ดอย่างถี่ถ้วน ความคิดเห็นเช่น "โค้ดดูถูกต้องสำหรับฉัน แต่ฉันไม่รู้สึกมั่นใจพอเกี่ยวกับพฤติกรรมที่จะให้ ACK" เป็นการมีส่วนร่วมที่เป็นประโยชน์อย่างสมบูรณ์
ตัวอย่างของความคิดเห็นที่เป็นประโยชน์อื่นๆ อาจเป็น "verified move-only" หาก PR รวมถึง move-only commits หรือ "คิดหนักเกี่ยวกับวิธีที่การเปลี่ยนแปลง X สามารถทำลาย Y แต่ไม่พบอะไร (หรือสถานการณ์นี้สามารถเกิดขึ้นได้หรือไม่)" ฯลฯ
เมื่อให้ ACK ให้ระบุ commits ที่ทบทวนโดยเพิ่มแฮชของ HEAD commit หรือ commit ที่คุณทบทวน วิธีที่ถูกต้องและไม่ต้องเชื่อใจคือการใช้แฮชจากการ checkout ในเครื่องท้องถิ่นของ branch และไม่ใช่จากหน้าเว็บ GitHub ด้วยวิธีนี้ เว้นแต่เครื่องมือในเครื่องของคุณจะถูกบุกรุก คุณตรวจสอบให้แน่ใจว่าคุณกำลัง ACK การเปลี่ยนแปลงที่แน่นอน นี่ยังเป็นประโยชน์เมื่อเกิด force push และลิงก์ไปยัง commits เก่าสูญหายไปบน GitHub
ACK แบบเต็มอาจดูเหมือน: "ACK fa2f991, ฉันสร้าง, รันการทดสอบ, ทดสอบด้วยตนเองโดยทำ X/Y/Z และทบทวนโค้ดและมันดูดี ฉันเห็นด้วยว่ามันสามารถ merge ได้"
สคริปต์ merge ของ Bitcoin Core ในปัจจุบันจะคัดลอกไปยัง merge commit ย่อหน้าแรกของแต่ละความคิดเห็นการทบทวน ACK ที่เกี่ยวข้องกับ HEAD commit ในเวลาที่ merge โปรดจำไว้ว่าสิ่งที่คุณเขียนที่นั่นที่ถูกคัดลอกโดยสคริปต์ merge จะอยู่ในประวัติ git ตลอดไป
PR ที่ซับซ้อนหรือมีความเสี่ยงมากขึ้นอาจต้องการ ACKs จากประสบการณ์อย่างน้อย 3-4 รายการก่อนที่จะ merge
ผู้ทบทวน Bitcoin Core มักใช้ระบบการลงคะแนนเสียง Apache ในความคิดเห็นของพวกเขา นี่คือตัวอย่าง
ทบทวนโค้ด ไม่ใช่ผู้มีส่วนร่วมหรือความคิดเห็นของพวกเขา
เมื่อคุณไม่เห็นด้วย ให้แสดงมุมมองของคุณครั้งเดียวและเดินหน้าต่อ นี่คือตัวอย่าง อย่าทำให้ส่วนความคิดเห็นเต็มไปด้วยข้อความ ตำหนิผู้อื่น หรือตอบสนองมากเกินไป มีความอดทน ไม่ก้าวร้าว ผลักดัน หรือข่มขู่ จำไว้ว่าสิ่งสำคัญที่สุดอาจไม่ใช่ปัญหาที่กำลังหารือ แต่เป็นความสัมพันธ์ของคุณกับผู้มีส่วนร่วมคนอื่นๆ
ในฐานะผู้มีส่วนร่วมใหม่ ให้ระมัดระวังในการให้ NACK สันนิษฐานโดยค่าเริ่มต้นว่าคุณอาจขาดความเข้าใจหรือบริบท หากคุณ NACK ให้เหตุผลที่ดี นี่คือตัวอย่างหนึ่ง
ผู้มีส่วนร่วมใน Bitcoin Core บางคนลงนามและ OpenTimestamp ACKs ของพวกเขา แม้ว่าสิ่งนี้จะอยู่นอกขอบเขตของเอกสารนี้ มันเป็นเรื่องง่ายอย่างน่าประหลาดใจที่จะลงนาม commits ของคุณโดยใช้ OpenTimestamps Git Integration
หลังจากสักพัก คุณจะสังเกตเห็นว่าผู้มีส่วนร่วมบางครั้งทบทวนโดยใช้ความคิดเห็นแบบพับเก็บได้ เจ๋ง คุณอาจคิด ฉันทำอย่างไร? มันทำได้โดยใช้แท็ก HTML details นี่คือวิธี
ขอขอบคุณ Steve Lee (moneyball) และ Michael Folkson สำหรับการตรวจทานบทความนี้และข้อเสนอแนะของพวกเขา
บทความนี้รวมถึงข้อคิดเห็นที่สังเกตได้จาก GitHub และ IRC โดยนักพัฒนา Bitcoin Core ต่อไปนี้ซึ่งสมควรได้รับเครดิต: Wladimir van der Laan, Marco Falke, Pieter Wuille, Gregory Maxwell, Anthony Towns และ Russ Yanofsky
ตลอดหลายปีที่ผ่านมา ผมเริ่มรู้สึกหมดศรัทธาต่ออิทธิพลศูนย์กลางของ BDFLs (Benevolent Dictators For Life) ในภาษาโปรแกรมและโครงการโอเพ่นซอร์สต่าง ๆ การอุทิศตนอย่างถ่อมตนของ Wladimir van der Laan ต่อ Bitcoin มาอย่างยาวนาน ได้จุดประกายความเป็นไปได้ให้ผมกลับมามีส่วนร่วมในโลกโอเพ่นซอร์สอีกครั้ง
สุดท้ายนี้ ขอขอบคุณผู้ร่วมพัฒนา Bitcoin Core ทุกท่านสำหรับความอดทนกับความพยายามในการรีวิวของผมที่ผ่านมา โดยเฉพาะอย่างยิ่ง John Newbery, Marco Falke, João Barbosa, practicalswift, Gregory Sanders, Jonas Schnelli, Pieter Wuille และ Wladimir van der Laan รวมถึง Adam Jonas และ John Newbery สำหรับคำแนะนำและแนวทางตั้งแต่เริ่มต้น
ด้วยความเคารพ,
Jon Atack
ACK, NACK: คำนิยามและที่มาอยู่ และ