istio.io
1.0.0
| เว็บไซต์ | สถานะ |
|---|---|
| istio.io | |
| เบื้องต้น | |
| Archive.istio.io |
ที่เก็บนี้มีซอร์สโค้ดสำหรับ istio.io และเบื้องต้น
โปรดดูไฟล์ Main Istio Readme เพื่อเรียนรู้เกี่ยวกับโครงการ ISTIO โดยรวมและวิธีติดต่อกับเรา หากต้องการเรียนรู้วิธีที่คุณสามารถมีส่วนร่วมในส่วนประกอบของ ISTIO ได้โปรดดูแนวทางการบริจาคของ ISTIO
หากต้องการเรียนรู้วิธีแก้ไขและสร้างเนื้อหาของ repo นี้โปรดดูที่การสร้างและแก้ไขหน้า
ISTIO รักษาสองรูปแบบของเว็บไซต์สาธารณะ
iStio.io เป็นเว็บไซต์หลักโดยแสดงเอกสารประกอบสำหรับการเปิดตัวผลิตภัณฑ์ปัจจุบัน iStio.io/archive มีสแน็ปช็อตของเอกสารประกอบสำหรับรุ่นก่อนหน้าของผลิตภัณฑ์ สิ่งนี้มีประโยชน์สำหรับลูกค้าที่ยังคงใช้รุ่นเก่าเหล่านี้
เบื้องต้น. istio.io มีเอกสารที่ได้รับการปรับปรุงอย่างแข็งขันสำหรับการเปิดตัวผลิตภัณฑ์ครั้งต่อไป
ผู้ใช้สามารถนำทางเล็กน้อยระหว่างรูปแบบที่แตกต่างกันของไซต์โดยใช้เมนูเกียร์ที่ด้านบนขวาของแต่ละหน้า ทั้งสองไซต์โฮสต์บน Netlify
การเปลี่ยนแปลงเอกสารมีความมุ่งมั่นเป็นหลักในสาขาหลักของ istio.io การเปลี่ยนแปลงที่เกิดขึ้นกับสาขานี้จะสะท้อนให้เห็นโดยอัตโนมัติในเบื้องต้นเกี่ยวกับ preliminary.istio.io
เนื้อหาของ iStio.io นำมาจากสาขารุ่นล่าสุด -XXX สาขาเฉพาะที่ใช้จะถูกกำหนดโดยการกำหนดค่าของโครงการ istio.io Netlify
การตรวจสอบการอัปเดตของสาขาหลักจะอัปเดตเบื้องต้นโดยอัตโนมัติและจะสะท้อนให้เห็นใน istio.io ในครั้งต่อไปที่มีการสร้างรุ่นต่อไปซึ่งอาจเป็นเวลาหลายสัปดาห์ในอนาคต หากคุณต้องการให้มีการเปลี่ยนแปลงบางอย่างที่จะสะท้อนให้เห็นทันทีใน iStio.io คุณต้องตรวจสอบการเปลี่ยนแปลงของคุณทั้งในสาขาหลักและสาขารุ่นปัจจุบัน (ชื่อ release-<MAJOR>.<MINOR> เช่น release-1.7 )
กระบวนการนี้สามารถดูแลโดยอัตโนมัติโดยโครงสร้างพื้นฐานของเรา หากคุณส่ง PR ไปยังสาขาหลักและใส่คำอธิบายประกอบการประชาสัมพันธ์ด้วยฉลาก cherrypick/release-<MAJOR>.<MINOR> จากนั้นทันทีที่ PR ของคุณถูกรวมเข้ากับ Master มันจะถูกรวมเข้ากับสาขารุ่นที่ระบุ
นี่คือขั้นตอนที่จำเป็นในการสร้างเวอร์ชันเอกสารใหม่ สมมติว่า ISTIO เวอร์ชันปัจจุบันคือ 1.6 และคุณต้องการแนะนำ 1.7 ซึ่งอยู่ระหว่างการพัฒนา
Run make prepare-1.7.0 และนั่นก็คือ สิ่งนี้จะคว้าเอกสารอ้างอิงล่าสุดจากสาขา Source ISTIO ใหม่ลงในโฟลเดอร์ content/en/docs/reference
สำหรับการวิ่งแบบแห้งก่อนที่จะเปิดตัวอย่างเป็นทางการ make release-1.7.0-dry-run ซึ่งจะสร้างสาขาใหม่ release-1.7-dry-run เท่านั้นและไม่ได้สัมผัสสาขาอื่น ๆ
ในวันที่เปิดตัว Run make release-1.7.0 สิ่งนี้ทำให้เป้าหมายจะเปลี่ยนตัวแปรบางอย่างใน master และ release-1.6 และสร้างสาขาใหม่ release-1.7 สำหรับเวอร์ชันใหม่
ไปที่โครงการ istio.io บน Netlify และทำสิ่งต่อไปนี้:
เปลี่ยนสาขาที่สร้างขึ้นจากสาขารุ่นก่อนหน้าเป็นสาขารีลีสใหม่ในกรณีนี้ release-1.7 (หรือ release-1.7-dry-run ตามความเหมาะสม)
เลือกตัวเลือกเพื่อทริกเกอร์การสร้างใหม่และการปรับใช้ใหม่ทันที
เมื่อการปรับใช้เสร็จแล้วให้เรียกดู iStio.io และตรวจสอบให้แน่ใจว่าทุกอย่างดูดี
ไปที่เครื่องมือค้นหาของ Google Custom และทำสิ่งต่อไปนี้:
ดาวน์โหลดไฟล์บริบท ISTIO.IO CSE จากแท็บขั้นสูง
เพิ่ม facetItem ใหม่ที่ด้านบนของไฟล์ที่มีหมายเลขเวอร์ชันรุ่นก่อนหน้า ในกรณีนี้นี่จะเป็น V1.6
อัปโหลดไฟล์บริบท CSE ที่อัปเดตไปยังไซต์
ในส่วนการตั้งค่าเพิ่มไซต์ใหม่ที่ครอบคลุมไดเรกทอรีเก็บถาวรของรุ่นก่อนหน้า ในกรณีนี้ URL ของไซต์จะเป็น istio.io/v1.6/* ตั้งค่าฉลากของเว็บไซต์นี้เป็นชื่อของรายการ facet ที่สร้างขึ้นด้านบน ( V1.6 ในกรณีนี้)
ไม่กี่วันก่อนการเปิดตัวแพทช์ผู้จัดการรุ่นควรแจ้งให้ทราบถึง DOC WG ว่าการสร้างนั้นถูกสร้างขึ้นและกำลังเริ่มต้นการทดสอบวุฒิการศึกษาระยะยาว ในเวลานี้ให้เลื่อนการทดสอบ DOC Automation เพื่อใช้รีลีสใหม่เพื่อตรวจสอบการทดสอบ DOC อัตโนมัติ
หากต้องการย้ายไปยังรีลีสใหม่ (ตรวจสอบให้แน่ใจว่าคุณอยู่ในสาขาการเปิดตัวของแพทช์):
Run go get istio.io/istio@AXY && go mod tidy
สร้างการประชาสัมพันธ์ด้วยการ go.* เปลี่ยนแปลง
การสร้างการเปิดตัวแพตช์ใหม่เกี่ยวข้องกับการแก้ไขไฟล์สองสามไฟล์:
แก้ไข data/args.yml และเปลี่ยนฟิลด์ full_version เป็น "AXY" นี่เป็นสิ่งจำเป็นสำหรับแพตช์ของรุ่น current เท่านั้น
กรอกบันทึกย่อการเปิดตัวสำหรับการเปิดตัวโดยการแก้ไข content/en/news/releases/AXx/announcing-AXY/index.md นี่คือที่ที่คุณอธิบายการเปลี่ยนแปลงในการเปิดตัว โปรดดูไฟล์อื่น ๆ ที่มีอยู่เช่นเนื้อหาและเค้าโครง
เรียกใช้ make update_ref_docs เพื่อรับเอกสารอ้างอิงล่าสุด โดยปกติแล้วนี่เป็นสิ่งจำเป็นสำหรับแพตช์ของรุ่น current เท่านั้น หากจำเป็นในรุ่นก่อนหน้าให้ดูการอัปเดตการเก็บถาวร
หากเวอร์ชันที่เก็บถาวรในสาขาใหม่ (เช่น release-1.7:archive/v1.6 ) จะต้องได้รับการปรับปรุงเนื่องจากการเปลี่ยนแปลงในสาขารุ่นเก่า ( release-1.6 ในกรณีนี้) คุณสามารถเรียกใช้ make build-old-archive-1.6.0 release-1.6 master master หากการอัปเดตนี้ต้องสะท้อนให้เห็นใน istio.io การประชาสัมพันธ์อาจถูกเลือกเชอร์รี่ไปยังสาขาสำหรับการเปิดตัว current
สตรีมรีลีสเริ่มต้นด้วย release-1.6 มีการทดสอบสำหรับเนื้อหาทดสอบ การทดสอบการเปิดตัวแต่ละครั้งกับรุ่น ISTIO/commit เฉพาะ เมื่อทีมงานเปิดตัวมีการสร้าง 1.xy พร้อมสำหรับการทดสอบระยะยาวพวกเขาควรมาที่ทีม DOCS เพื่อทำการทดสอบสำหรับการเปิดการเปิดตัวครั้งนั้นเริ่มทำงานกับการสร้าง
มีสองประเภทของการสร้าง public และ private DEV และการเปิดตัวแบบปกติสร้างขึ้นจาก repos สาธารณะของเราและมีภาพในที่เก็บข้อมูลที่เข้าถึงได้สาธารณะและได้รับการพิจารณาให้ public การสร้าง Private คือสิ่งที่เราไม่สามารถเปิดเผยได้มากนักก่อนที่จะเปิดตัว โดยทั่วไปจะเป็นการแจ้งล่วงหน้าว่าการเปิดตัวจะเกิดขึ้นในสองสัปดาห์สำหรับ CVES เนื่องจากเราไม่สามารถเปิดเผยอะไรได้ก่อนการเปิดตัวจริงแหล่งที่มาและภาพที่สร้างขึ้นจึงอยู่ใน repos ส่วนตัว เนื่องจากแหล่งที่มาและรูปภาพเป็นส่วนตัวเราไม่สามารถย้ายไปหาพวกเขาได้จนกว่าพวกเขาจะได้รับการเผยแพร่ต่อสาธารณะและทำให้ไม่มีการทดสอบการเปิดตัวใน istio.io ก่อน ความแตกต่างสำหรับการสร้าง private คือภาพที่เราทดสอบไม่เคยถูกสร้างขึ้นในพื้นที่เก็บข้อมูล public GCR.IO ดังนั้นในกรณีนั้นเราใช้ภาพ Docker.io หนึ่งอาจถามว่าทำไมเราไม่ใช้ภาพปล่อยจาก Docker.io เสมอ เนื่องจากเราต้องการทดสอบการสร้าง public ก่อนที่จะเปิดตัวรูปภาพจึงยังไม่ได้อยู่ใน Docker.io
สำหรับการสร้างสาธารณะ:
go get istio.io/istio@commit && go mod tidyสำหรับการสร้างส่วนตัว (ทำหลังจากสร้างการสร้าง):
go get istio.io/[email protected] && go mod tidyสำหรับการสร้างทั้งสองเราต้องการตรวจสอบว่าฮับ/แท็กนั้นถูกต้องใน makefile.core.mk (พวกเขาเปลี่ยนไปขึ้นอยู่กับว่าใช้งานส่วนตัวหรือสาธารณะ) มองหาส่วนที่คล้ายกับ:
# If one needs to test before a docker.io build is available (using a public test build),
# the export HUB and TAG can be commented out, and the initial HUB un-commented
HUB ?= gcr.io/istio-testing
# export HUB ?= docker.io/istio
# export TAG ?= 1.7.3
สำหรับการสร้างสาธารณะ export HUB/TAG S จะไม่ทำให้ไม่รู้สึกตัวและมีค่าที่ถูกต้อง สำหรับการสร้างส่วนตัวหรือสาขา master ฮับจะไม่รู้สึกตัว
สุดท้ายสร้างและส่ง PR พร้อมกับการเปลี่ยนแปลงและสามารถดูผลการทดสอบใน PR โดยปกติแล้วการประชาสัมพันธ์จะไม่รวมกันจนกว่าจะมีการเปิดตัว (บางครั้งมีการสร้างหลายครั้งสำหรับการเปิดตัว)
เอกสารจำนวนมากบนไซต์ ISTIO แสดงให้เห็นถึงคุณสมบัติที่ใช้คำสั่งที่อาจทำงานต่อไปหรือไม่ทำงานต่อไปในขณะที่ ISTIO วิวัฒนาการมาจากการเปิดตัวไปจนถึงการเปิดตัว เพื่อให้แน่ใจว่าคำแนะนำที่บันทึกไว้ยังคงอยู่ในปัจจุบันโดยมีการทดสอบด้วยตนเองอย่างต่อเนื่องน้อยที่สุดเท่าที่จะทำได้เราได้สร้างกรอบการทำงานเพื่อทำการทดสอบเอกสารเหล่านี้โดยอัตโนมัติ
ทุกหน้าบน istio.io ที่สามารถทดสอบได้รวมถึงตัวบ่งชี้ PAGE TEST ภายใต้ชื่อหน้า ตัวอย่างเช่น:
เครื่องหมายถูกสีเขียวระบุว่ามีการทดสอบอัตโนมัติสำหรับหน้า หน้ามีข้อมูลล่าสุดและทำงานตามที่บันทึกไว้
ในทางกลับกันสีเทา X หมายความว่ายังไม่มีการทดสอบอัตโนมัติสำหรับเพจ แต่ยัง เราขอขอบคุณถ้าคุณต้องการช่วยสร้าง! เป้าหมายของเราคือการทดสอบอัตโนมัติในที่สุดสำหรับเอกสารที่ทดสอบได้ทุกฉบับที่เผยแพร่บนเว็บไซต์ ISTIO
ดูการทดสอบ readme สำหรับข้อมูลเพิ่มเติม
ไซต์ถูกแปลเป็นหลายภาษา แหล่งที่มาของความจริงคือเนื้อหาภาษาอังกฤษในขณะที่ภาษาอื่น ๆ ได้มาและมีแนวโน้มที่จะล้าหลังเล็กน้อย แต่ละภาษาของไซต์จะได้รับไดเรกทอรีเนื้อหาที่มีอยู่ในตัวเองอย่างเต็มที่และไฟล์ตารางการแปล ภาษาถูกระบุโดยใช้รหัสภาษา 2 ตัวอักษรนานาชาติ เนื้อหาไซต์หลักอยู่ใน content/<language code> (เช่น content/en ) และตารางการแปลเป็นไฟล์ toml-format ใน i18n<language code>.toml (เช่น i18n/en.toml )
การเริ่มต้นใช้งานการแปลนั้นค่อนข้างง่าย:
สร้างสำเนาเต็มของไดเรกทอรี content/en สำหรับภาษาของคุณ ตัวอย่างเช่นคุณจะคัดลอก content/en ไปยัง content/fr หากคุณทำการแปลภาษาฝรั่งเศส
อัปเดตลิงก์ทั้งหมดในไดเรกทอรีเนื้อหาใหม่ของคุณเพื่อชี้ไปที่ไดเรกทอรีเนื้อหาของคุณแทนเนื้อหาภาษาอังกฤษ ตัวอย่างเช่นหากคุณทำการแปลภาษาฝรั่งเศสคุณจะเปลี่ยนลิงก์เช่น [a doc](/docs/a/b/c) เป็น [a doc](/fr/docs/a/b/c)
ลบคำสั่ง aliases ทั้งหมดในด้านหน้าของหน้าเนื้อหาทั้งหมด นามแฝงจะถูกใช้เมื่อย้ายหน้าไปยังตำแหน่งใหม่ดังนั้นจึงไม่เป็นที่ต้องการสำหรับเนื้อหาใหม่ล่าสุด
สร้างสำเนาของไฟล์ i18n/en.toml สำหรับภาษาของคุณ ตัวอย่างเช่นคุณจะคัดลอก i18n/en.toml เป็น i18n/fr.toml หากคุณกำลังแปลภาษาฝรั่งเศส ไฟล์นี้มีข้อความที่แสดงโดยโครงสร้างพื้นฐานของไซต์สำหรับสิ่งต่าง ๆ เช่นเมนูและวัสดุมาตรฐานอื่น ๆ
แก้ไขไฟล์ hugo.toml เพื่อแสดงรายการภาษาใหม่ของคุณ ค้นหารายการ [languages] และเพิ่มรายการใหม่ สิ่งนี้บอกให้ผู้สร้างไซต์ Hugo ประมวลผลเนื้อหาของคุณ
แก้ไข scripts/lint_site.sh และค้นหา check_content เพิ่มการโทรอื่นเพื่อ check_content สำหรับไดเรกทอรีเนื้อหาใหม่ของคุณ สิ่งนี้ทำให้มั่นใจได้ว่ากฎผ้าสำลีใช้กับเนื้อหาใหม่ของคุณ
แก้ไขไฟล์ src/ts/lang.ts และเพิ่มภาษาใหม่ของคุณ สิ่งนี้จะเพิ่มภาษาของคุณลงในปุ่มสลับภาษาที่มีอยู่ในเบื้องต้น. istio.io และจะทำให้เป็นภาษาของคุณจะได้รับการสนับสนุนในเมนูการเลือกภาษา
รับผู้ดูแลระบบ istio GitHub เพื่อสร้างทีมผู้ดูแลใหม่สำหรับภาษาของคุณ สำหรับภาษาฝรั่งเศสนี่จะเป็น WG - Docs Maintainers/French
แก้ไข CODEOWNERS ไฟล์และเพิ่มรายการสำหรับภาษาของคุณเพื่อให้ทีมใหม่ที่คุณได้สร้างความเป็นเจ้าของมากกว่าเนื้อหาที่แปลและไฟล์ตารางการแปล
จากนั้นคุณสามารถกระทำการเปลี่ยนแปลงทั้งหมดเหล่านี้และคุณสามารถเริ่มแปลเนื้อหาและไฟล์แปลในแบบที่เพิ่มขึ้นอย่างหมดจด เมื่อคุณสร้างเว็บไซต์คุณจะพบเนื้อหาของคุณที่ <url>/<language code> ตัวอย่างเช่นเมื่อคุณตรวจสอบทุกอย่างแล้วคุณควรจะสามารถไปที่เนื้อหาของคุณได้ที่ https://preliminary.istio.io/fr หากคุณทำการแปลภาษาฝรั่งเศส
เมื่อการแปลของคุณเสร็จสมบูรณ์และคุณพร้อมที่จะเผยแพร่ไปทั่วโลกมีการเปลี่ยนแปลงอื่น ๆ อีกสองสามอย่างที่คุณต้องทำ:
แก้ไข layouts/index.redir ค้นหา translated sites และเพิ่มบรรทัดสำหรับภาษาของคุณ สิ่งนี้จะทำให้ผู้ใช้มาที่ไซต์เป็นครั้งแรกที่จะเปลี่ยนเส้นทางไปยังเนื้อหาที่แปลโดยอัตโนมัติที่เหมาะสมสำหรับพวกเขา สำหรับภาษาฝรั่งเศสนี่จะเป็น:
/ /fr 302 Language=fr
แก้ไขเล layouts/partials/headers.html html ค้นหา switch-lang แล้วคุณจะพบคำจำกัดความสำหรับเมนูการเลือกภาษา เพิ่มบรรทัดสำหรับภาษาใหม่ของคุณ
และนั่นคือ
เรามีการตรวจสอบจำนวนมากเพื่อให้แน่ใจว่ามีการรักษาค่าคงที่จำนวนมากเพื่อช่วยให้คุณภาพโดยรวมของไซต์ ตัวอย่างเช่นเราไม่อนุญาตให้ตรวจสอบในลิงค์ที่เสียและเราทำการตรวจสอบสะกด มีบางสิ่งที่ยากที่จะตรวจสอบผ่านระบบอัตโนมัติอย่างเป็นระบบและต้องการให้มนุษย์ตรวจสอบในขณะนี้เพื่อให้แน่ใจว่าทุกอย่างทำได้ดี
เป็นความคิดที่ดีที่จะเรียกใช้รายการนี้ก่อนการเปิดตัวไซต์สำคัญทุกครั้ง:
ตรวจสอบให้แน่ใจว่าการอ้างอิงถึง repos iStio บน GitHub ไม่ใช่ชื่อสาขาฮาร์ดโฟเวต ค้นหาการใช้งาน /release-1 หรือ /master ตลอดทั้งไฟล์ markdown ทั้งหมดและแทนที่ไฟล์ที่มี {{<source_branch_name>}} แทนซึ่งสร้างชื่อสาขาที่เหมาะสมกับเวอร์ชัน
ตรวจสอบไฟล์. spelling สำหรับคำที่ไม่ควรอยู่ในนั้น ชื่อประเภทโดยเฉพาะอย่างยิ่งมักจะคืบคลานเข้ามาที่นี่ ชื่อประเภทไม่ควรอยู่ในพจนานุกรมและควรแสดงด้วย backticks แทน ลบรายการออกจากพจนานุกรมและแก้ไขข้อผิดพลาดในการตรวจสอบการสะกดคำใด ๆ ที่เกิดขึ้น
ตรวจสอบให้แน่ใจว่าเป็นตัวพิมพ์ใหญ่ที่เหมาะสม ชื่อเอกสารจะต้องเป็นตัวพิมพ์ใหญ่อย่างเต็มที่ (เช่น "นี่คือชื่อที่ถูกต้อง") ในขณะที่ส่วนหัวส่วนควรใช้ตัวอักษรตัวพิมพ์ใหญ่ตัวแรกเท่านั้น (เช่น "นี่คือหัวข้อที่ถูกต้อง")
ตรวจสอบให้แน่ใจว่าบล็อกข้อความ preformatted ที่อ้างอิงไฟล์จาก istio gitHub repos ใช้ @@ ไวยากรณ์เพื่อสร้างลิงก์ไปยังเนื้อหา ดูที่นี่สำหรับบริบท
