pkg.go.dev — มากกว่าแค่ที่อ่านเอกสาร Go

pkg.go.dev — มากกว่าแค่ที่อ่านเอกสาร Go

ถ้าคุณเขียน Go — คุณน่าจะเคยเปิด pkg.go.dev เพื่ออ่านเอกสาร package สักตัว

แต่ pkg.go.dev ไม่ใช่แค่ reader — มันคือ enforcement mechanism สำหรับ best practices ของระบบนิเวศ Go ทั้งหมด

ทุกครั้งที่มีคนเปิดหน้า package ของคุณ — pkg.go.dev จะแสดงผลการตรวจสอบ 4 อย่าง: มี go.mod ไหม, license เป็นอะไร, มี tagged version หรือเปล่า, version เสถียรหรือยัง

ถ้าคุณเขียน library แล้ว pkg.go.dev ไม่ขึ้นเครื่องหมายถูก — มันคือป้ายไฟนีออนที่บอกทุกคนว่า "package นี้ยังไม่พร้อมสำหรับ production"

---

4 เครื่องหมายที่ pkg.go.dev เช็ค

1. Has go.mod file

go.mod คือมาตรฐาน dependency management ของ Go — ตั้งแต่ Go 1.11 — และ pkg.go.dev ถือว่าการมี go.mod คือ baseline

ไม่มี go.mod → ไม่ใช่ Go module → ไม่มี versioning จริง → pkg.go.dev จะแสดง package แบบไม่มีข้อมูลเวอร์ชัน

สิ่งที่ควรทำ: ทุก repo ควรมี go.mod — แม้จะเป็น package เล็ก ๆ ก็ตาม

2. Redistributable license

pkg.go.dev ตรวจสอบ license ของ package — และจะแสดงเฉพาะ license ที่ redistributable (MIT, BSD, Apache 2.0, etc.)

license ที่ restrictive เกินไป หรือไม่พบ license → pkg.go.dev อาจไม่แสดง documentation บางส่วน หรือขึ้นคำเตือน

สิ่งที่ควรทำ: ใส่ LICENSE file ใน repo — MIT หรือ BSD หรือ Apache 2.0

3. Tagged version

Go modules ใช้ Git tags เป็นเวอร์ชัน — v1.0.0, v1.2.3 — และ go get ให้ความสำคัญกับ tagged versions ก่อน commit hash

ไม่มี tag → go get ต้องใช้ pseudo-version (v0.0.0-20250101000000-abc123) — ซึ่งไม่ stable และ importers ไม่มั่นใจ

สิ่งที่ควรทำ: tag ทุก release ด้วย semver — git tag v1.0.0 && git push origin v1.0.0

4. Stable version

Projects ที่ v0.x.x ถูกมองว่า experimental — breaking changes เกิดได้ตลอดเวลา — ไม่มีสัญญาว่าจะ backward compatible

เมื่อถึง v1.0.0 — คือสัญญาว่า public API จะไม่เปลี่ยนแบบ breaking ภายใน major version เดียวกัน

pkg.go.dev แสดงสถานะนี้ให้ทุกคนเห็น — "stable" หรือ "experimental" — และมันมีผลต่อการตัดสินใจของคนที่จะ import package ของคุณ

สิ่งที่ควรทำ: เมื่อ API นิ่ง — release v1.0.0 — และถ้าต้อง breaking change — ขึ้น major version ใหม่ (v2.0.0)

---

มากกว่า 4 เครื่องหมาย — สิ่งที่ pkg.go.dev ทำเบื้องหลัง

Documentation จาก source โดยตรง

pkg.go.dev ดึง source code จาก Go Module Mirror (proxy.golang.org) — และ generate documentation จาก source โดยตรง — ไม่ต้องอัปโหลดอะไรเอง

แค่ push code + tag → documentation ปรากฏบน pkg.go.dev ภายในไม่กี่นาที

Build Context

package บางตัวทำงานต่างกันบน OS/architecture ต่างกัน — pkg.go.dev แสดง build context ให้เห็น — เช่น linux/amd64, js/wasm

และมี dropdown ให้สลับดู document สำหรับ build context อื่น

การเพิ่ม package ใหม่

ถ้า package ยังไม่ปรากฏบน pkg.go.dev — แค่เข้า URL นั้นตรง ๆ แล้วกด "Request":

https://pkg.go.dev/example.com/my/module

หรือ go get package นั้นผ่าน proxy:

GOPROXY=https://proxy.golang.org go get example.com/my/module@v1.0.0

Retract เวอร์ชันที่มีปัญหา

ถ้า release เวอร์ชันที่มีบั๊กร้ายแรง — แก้ด้วย retract directive ใน go.mod:

retract v1.2.3 // security vulnerability

go get และ pkg.go.dev จะไม่แนะนำเวอร์ชันนั้นอีก — แต่ยังดาวน์โหลดได้ (retract ≠ delete)

---

เขียน package comment ให้ดี — มันไปโผล่บน go.dev

ประโยคแรกของ package comment คือสิ่งที่ go.dev ใช้เป็น search result snippet

// Package httputil provides HTTP utility functions, complementing the
// more common ones in the net/http package.
package httputil

ประโยคนี้คือสิ่งที่จะปรากฏเวลามีคน search บน go.dev — และทุกคนที่เปิดหน้า pkg.go.dev ของคุณ — จะเห็นประโยคนี้เป็นอันดับแรก

สิ่งที่ควรทำ: ประโยคแรกของ package comment ควรเป็น summary ที่สมบูรณ์ — ไม่ใช่แค่ชื่อ package

---

สรุป

pkg.go.dev คือ public scoreboard ของทุก Go package — และ 4 เครื่องหมายที่มันเช็คคือสิ่งที่ทุก package ควรมี

✅ go.mod
✅ Redistributable license (MIT/BSD/Apache)
✅ Tagged version (semver)
✅ Stable version (v1.0.0+)

ไม่มีอะไรซับซ้อน — แต่เป็นสัญญาณว่า "package นี้พร้อมให้คนอื่นใช้"

📚 อ่านต่อ:

• pkg.go.dev/about — official documentation
• Go Modules Reference — versioning, retract, compatibility