DEP-14 Note

บันทึกเตือนความจำสำหรับการทำตาม DEP-14: Recommended layout for Git packaging repositories เพื่อนำไปใช้ทำกับแพกเกจอื่น ๆ ในความดูแลของผมต่อไป

สำหรับ Debian package ปกติที่จัดการเวอร์ชันบน Git และใช้ git-buildpackage ในการ build นั้น จะมี branch layout ดังนี้:

master
pristine-tar
upstream

• master เป็น branch หลักที่มีทั้ง upstream source tree และ Debian control files ครบสำหรับ build deb
• upstream เป็น branch ที่เก็บ upstream source tree ซึ่ง maintainer จะ import source รุ่นใหม่เข้าที่นี่ก่อน (ถ้ามีการ repack เพื่อให้สอดคล้องกับ DFSG ก็ repack ก่อน import) แล้วจึง merge เข้าที่ master เพื่อเป็นการปรับรุ่น upstream ของ deb เอง
• pristine-tar เป็น branch สำหรับ regenerate binary tarball รุ่นต่าง ๆ ของ upstream เพื่อใช้เป็นไฟล์ *.orig.tar.[gz|bz2|xz] โดยเก็บเฉพาะ delta ระหว่างรุ่นต่าง ๆ เพื่อให้ใช้เนื้อที่อย่างมีประสิทธิภาพสูงสุด

ศึกษารายละเอียดเพิ่มเติมได้ที่:

• Debian Wiki
• บันทึกของ Russ Allbery

DEP-14 ได้แนะนำให้ใช้ branch layout แบบใหม่ เพื่อให้ Debian derivatives ต่าง ๆ ทำงานได้สะดวกขึ้น พร้อมกับเป็นการเตรียมการสำหรับเครื่องมือสร้างแพกเกจบน Git ต่าง ๆ ที่จะมีต่อไปในอนาคต

สำหรับแพกเกจใน Debian เอง โดยสรุปแล้วจะมีการเปลี่ยนแปลง branch layout ภาคบังคับอยู่ 2 รายการ คือ:

• master เปลี่ยนเป็น debian/master
• upstream เปลี่ยนเป็น upstream/latest

ทำให้มี branch layout ขั้นต่ำคือ:

debian/master
pristine-tar
upstream/latest

ที่เหลือก็ขึ้นอยู่กับความเปลี่ยนแปลงที่เกิดขึ้นกับแพกเกจ เช่น:

• ถ้ามีการ update ใน stable release (เช่น security update, proposed update, backport) ก็ทำใน branch debian/jessie, debian/wheezy, debian/wheezy-backports ฯลฯ แล้วแต่กรณี
• ถ้ามี experimental upload ก็ทำใน branch debian/experimental ซึ่งเป็น branch ชั่วคราวจนกว่าจะ merge เข้า debian/master หรือถ้าแพกเกจไหนมี experimental upload คู่ขนานกับ stable upload อยู่เป็นนิตย์ ก็อาจจะแทน branch debian/master ด้วย debian/sid แล้วก็ไม่ต้องลบ branch debian/experimental เลยก็ได้
• ถ้าต้อง update upstream ขนานกันหลาย branch ก็อาจจะใช้ upstream/latest เก็บ development release ล่าสุด และสร้าง branch เช่น upstream/1.2.x ไว้เก็บ upstream รุ่น 1.2.*

สำหรับแพกเกจที่ผมดูแล ส่งตรงจาก linux.thai.net ซึ่งที่ผ่านมามีแต่ release เป็นเส้นตรง ไม่มีแยกแขนง ก็มักไม่มีความซับซ้อนอะไร (ยกเว้นตอนที่มี security update) สิ่งที่ต้องทำในตอนนี้จึงมีเพียง 3 ขั้นตอน:

1. เปลี่ยนชื่อ branch upstream เป็น upstream/latest
2. เปลี่ยนชื่อ branch master เป็น debian/master
3. เพิ่มไฟล์ debian/gbp.conf เพื่อระบุให้ใช้ branch ชื่อใหม่

เปลี่ยนชื่อ branch upstream

การเปลี่ยนชื่อ Git remote branch สามารถทำได้ตามขั้นตอนดังนี้

1. เปลี่ยนชื่อ local branch

   $ git branch -m upstream upstream/latest
   

2. ลบ remote branch upstream

   $ git push origin :upstream
   

3. push local branch ชื่อใหม่ไปที่ remote

   $ git push --set-upstream origin upstream/latest
   

เปลี่ยนชื่อ branch master

โดยหลักการแล้วก็ทำเหมือนตอนเปลี่ยนชื่อ branch upstream นั่นแหละ แต่จะมีความไม่ตรงไปตรงมานิดหน่อย

1. เปลี่ยนชื่อ local branch

   $ git branch -m master debian/master
   

2. ลบ remote branch master

   ขั้นตอนนี้แหละที่ tricky ที่สุด เพราะ คุณกำลังจะลบ default branch (master) ออกจาก repository!

   ถ้าคุณใช้ Salsa ล่ะก็ hook script ของมันจะปฏิเสธไม่ให้ลบ default branch ผ่านการ push เลยทีเดียว คุณต้องทำผ่าน web interface ดังนี้

   1. เปลี่ยน default branch ไปที่อื่นก่อน โดยใช้เมนู Settings > General > Default Branch
   2. ลบ branch master โดยใช้เมนู Repository > Branches สังเกตว่า branch master จะถูก protect ไว้ ไม่สามารถลบผ่านการ push ได้ แต่ใช้ web interface ลบได้ โดยมันจะถามยืนยันก่อนลบ
3. push local branch ชื่อใหม่ไปที่ remote

   $ git push --set-upstream origin debian/master
   

4. เปลี่ยน default branch ให้ชี้มาที่ debian/master โดยใช้เมนู Settings > General > Default Branch

เพิ่มไฟล์ debian/gbp.conf

คุณอาจจะต้อง clone Git repository ใหม่อีกครั้ง เพื่อให้ค่าต่าง ๆ ของ origin ตรงกับของ remote (เช่น HEAD)

จากนั้น เพิ่มไฟล์ debian/gbp.conf ที่มีเนื้อหาดังนี้:

[DEFAULT]
pristine-tar = True
debian-branch = debian/master
upstream-branch = upstream/latest

ก็จะสามารถ build package ด้วย git-buildpackage ได้ตามปกติผ่าน branch layout ตาม DEP-14