istio.io
1.0.0
| Lokasi | Status |
|---|---|
| ISTIO.IO | |
| pendahuluan.istio.io | |
| archive.istio.io |
Repositori ini berisi kode sumber untuk iStio.io dan pendahuluan.istio.io.
Silakan lihat file ReadMe ISTIO utama untuk mempelajari tentang proyek ISTIO keseluruhan dan cara menghubungi kami. Untuk mempelajari bagaimana Anda dapat berkontribusi pada salah satu komponen ISTIO, silakan lihat Pedoman Kontribusi ISTIO.
Untuk mempelajari cara mengedit dan membangun konten repo ini, silakan merujuk ke membuat dan mengedit halaman.
ISTIO memelihara dua variasi situs publiknya.
ISTIO.IO adalah situs utama, menunjukkan dokumentasi untuk rilis produk saat ini. ISTIO.IO/Archive berisi snapshot dari dokumentasi untuk rilis produk sebelumnya. Ini berguna untuk pelanggan yang masih menggunakan rilis yang lebih lama ini.
pendahuluan.istio.io berisi dokumentasi yang diperbarui secara aktif untuk rilis produk berikutnya.
Pengguna dapat secara sepele menavigasi antara variasi situs yang berbeda menggunakan menu Gear di kanan atas setiap halaman. Kedua situs di -host di Netlify.
Perubahan dokumentasi terutama berkomitmen pada cabang utama ISTIO.IO. Perubahan yang dilakukan pada cabang ini secara otomatis tercermin pada pendahuluan.istio.io.
Konten ISTIO.IO diambil dari cabang rilis-XXX terbaru. Cabang spesifik yang digunakan ditentukan oleh konfigurasi proyek ISTIO.IO Netlify.
Memeriksa pembaruan ke cabang master akan secara otomatis memperbarui pendahuluan.istio.io, dan hanya akan tercermin di iStio.io saat rilis berikutnya dibuat, yang dapat beberapa minggu di masa mendatang. Jika Anda ingin beberapa perubahan akan segera tercermin di ISTIO.IO, Anda perlu memeriksa perubahan Anda baik pada cabang master dan ke cabang rilis saat ini (bernama release-<MAJOR>.<MINOR> seperti release-1.7 ).
Proses ini dapat diurus secara otomatis oleh infrastruktur kami. Jika Anda mengirimkan PR ke cabang master dan memberi anotasi pada PR dengan label cherrypick/release-<MAJOR>.<MINOR> , maka segera setelah PR Anda digabungkan menjadi Master, itu akan digabungkan ke dalam cabang rilis yang ditentukan.
Berikut adalah langkah -langkah yang diperlukan untuk membuat versi dokumentasi baru. Mari kita asumsikan versi ISTIO saat ini adalah 1.6 dan Anda ingin memperkenalkan 1.7 yang telah sedang dikembangkan.
Jalankan make prepare-1.7.0 , dan hanya itu. Ini akan mengambil dokumen referensi terbaru dari cabang sumber iStio baru ke folder content/en/docs/reference .
Untuk menjalankan kering sebelum rilis resmi, RUN make release-1.7.0-dry-run , yang hanya akan membuat release-1.7-dry-run dan tidak menyentuh cabang lainnya.
Pada hari rilis, jalankan make release-1.7.0 . Ini membuat target akan mengubah beberapa variabel dalam master dan release-1.6 , dan membuat release-1.7 untuk versi baru.
Pergi ke proyek ISTIO.IO di Netlify dan lakukan hal berikut:
Ubah cabang yang dibangun dari cabang rilis sebelumnya ke cabang rilis baru, dalam hal ini release-1.7 (atau release-1.7-dry-run sesuai kebutuhan).
Pilih opsi untuk memicu pembangunan kembali dan pemindahan segera.
Setelah penempatan selesai, telusuri istio.io dan pastikan semuanya terlihat bagus.
Buka mesin pencari kustom Google dan lakukan hal berikut:
Unduh file konteks ISTIO.IO CSE dari tab Advanced.
Tambahkan facetitem baru di bagian atas file yang berisi nomor versi rilis sebelumnya. Dalam hal ini, ini akan menjadi V1.6 .
Unggah file konteks CSE yang diperbarui ke situs.
Di bagian pengaturan, tambahkan situs baru yang mencakup direktori arsip rilis sebelumnya. Dalam hal ini, URL situs adalah istio.io/v1.6/* . Atur label situs ini ke nama item facet yang dibuat di atas ( V1.6 dalam kasus ini).
Beberapa hari sebelum rilis patch, manajer rilis harus memberi tahu DOC WG bahwa rilis dibangun dan memulai tes kualifikasi yang berjalan lama. Pada saat ini, pindahkan tes otomasi DOC untuk menggunakan rilis baru untuk memverifikasi tiket pengujian DOC otomatis.
Untuk pindah ke rilis baru (pastikan Anda berada di cabang rilis patch):
Jalankan go get istio.io/istio@AXY && go mod tidy .
Buat PR dengan go.* Perubahan.
Membuat rilis patch baru melibatkan memodifikasi beberapa file:
Edit data/args.yml dan ubah bidang full_version menjadi "AXY" . Ini hanya diperlukan untuk sepetak rilis current .
Lengkapi catatan rilis untuk rilis dengan mengedit content/en/news/releases/AXx/announcing-AXY/index.md . Di sinilah Anda menggambarkan perubahan dalam rilis. Silakan lihat file lain yang ada misalnya konten dan tata letak.
Jalankan make update_ref_docs untuk mendapatkan dokumen referensi terbaru. Biasanya, ini hanya diperlukan untuk sepetak rilis current . Jika diperlukan dalam rilis sebelumnya, lihat memperbarui arsip.
Jika versi yang diarsipkan di cabang yang lebih baru (misalnya, release-1.7:archive/v1.6 ) perlu diperbarui karena perubahan dalam cabang rilis lama ( release-1.6 dalam kasus ini), Anda dapat menjalankan make build-old-archive-1.6.0 di cabang master , yang akan mengarsipkan kembali release-1.6 dan mengganti arsip sebelumnya di Cabang master . Jika pembaruan ini perlu tercermin dalam ISTIO.IO, PR dapat dipilih ceri ke cabang untuk rilis current .
Stream rilis dimulai dengan release-1.6 berisi tes untuk konten tes. Setiap tes rilis terhadap versi/komit ISTIO tertentu. Ketika tim rilis memiliki build, 1.xy , siap untuk tes jangka panjang mereka, mereka harus datang ke tim DOCS untuk melakukan pengujian untuk rilis rilis mulai berlari melawan build.
Ada dua jenis bangunan, public dan private . Bangunan Dev dan Release normal dibangun dari repo publik kami dan memiliki gambar di repositori yang dapat diakses publik dan dianggap public . Bangunan Private adalah tempat di mana kita tidak bisa mengungkapkan banyak sebelum rilis. Biasanya ini adalah pemberitahuan terlebih dahulu bahwa rilis akan terjadi dalam dua minggu untuk CVE. Karena kami tidak dapat mengungkapkan apa pun sebelum rilis yang sebenarnya, sumber dan gambar yang dibangun ada dalam repo pribadi. Karena sumber dan gambarnya pribadi, kami tidak dapat benar -benar pindah ke mereka sampai mereka dirilis secara publik, dan dengan demikian tidak ada pengujian awal rilis di ISTIO.IO. Perbedaan untuk build private adalah bahwa gambar yang kami uji tidak pernah dibuat di repositori GCR.IO public , jadi dalam hal ini kami menggunakan gambar Docker.io. Orang mungkin bertanya mengapa kami tidak selalu menggunakan gambar rilis dari Docker.io. Karena kami ingin menguji build public sebelum dirilis, gambar belum ada di Docker.io.
Untuk bangunan publik:
go get istio.io/istio@commit && go mod tidy .Untuk bangunan pribadi (ini dilakukan setelah build dirilis):
go get istio.io/[email protected] && go mod tidy .Untuk kedua bangunan, kami ingin memverifikasi bahwa hub/tag benar di makefile.core.mk (mereka berubah tergantung pada jika menggunakan bangunan pribadi atau publik). Cari bagian yang mirip dengan:
# 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
Untuk bangunan publik, export HUB/TAG S tidak akan dikomentasikan dan memiliki nilai yang benar. Untuk bangunan pribadi, atau cabang master , hub tidak akan dikomentasikan.
Akhirnya, buat dan kirimkan PR dengan perubahan dan orang dapat melihat hasil tes di PR. Biasanya, PR tidak akan benar -benar bergabung sampai rilis dirilis (kadang -kadang ada beberapa build untuk rilis).
Banyak dokumen di situs ISTIO mendemonstrasikan fitur menggunakan perintah yang mungkin atau mungkin tidak terus bekerja ketika ISTIO berevolusi dari rilis ke rilis. Untuk memastikan instruksi yang terdokumentasi tetap up to date dengan pengujian manual berkelanjutan sesedikit mungkin, kami telah membuat kerangka kerja untuk mengotomatisasi pengujian dokumen -dokumen ini.
Setiap halaman di iStio.io yang dapat diuji termasuk indikasi PAGE TEST di bawah judul halaman. Misalnya:
Tanda centang hijau menunjukkan tes otomatis tersedia untuk halaman ini. Halaman ini mutakhir dan berfungsi seperti yang didokumentasikan.
Grey X, di sisi lain, berarti belum ada tes otomatis yang tersedia untuk halaman tersebut. Kami akan menghargainya jika Anda ingin membantu membuatnya! Tujuan kami adalah untuk akhirnya memiliki tes otomatis untuk setiap dokumen yang dapat diuji yang diterbitkan di situs ISTIO.
Lihat tes readme untuk informasi lebih lanjut.
Situs ini diterjemahkan ke dalam berbagai bahasa. Sumber kebenaran adalah konten bahasa Inggris, sementara bahasa lain diturunkan dan karenanya cenderung sedikit tertinggal. Setiap bahasa situs mendapatkan direktori konten dan tabel terjemahan sepenuhnya mandiri. Bahasa diidentifikasi menggunakan kode bahasa 2-huruf internasional mereka. Konten situs utama terletak di content/<language code> (misalnya content/en ), dan tabel terjemahan adalah file format TOML di i18n<language code>.toml (misalnya i18n/en.toml ).
Memulai dengan terjemahan cukup sederhana:
Buat salinan lengkap direktori content/en untuk bahasa Anda. Misalnya, Anda akan menyalin content/en ke content/fr jika Anda melakukan terjemahan bahasa Prancis.
Perbarui semua tautan di direktori konten baru Anda untuk menunjuk ke direktori konten Anda alih -alih ke konten bahasa Inggris. Misalnya, jika Anda melakukan terjemahan bahasa Prancis, Anda akan mengubah tautan seperti [a doc](/docs/a/b/c) menjadi [a doc](/fr/docs/a/b/c) .
Hapus semua arahan aliases di bagian depan semua halaman konten. Alias digunakan saat memindahkan halaman ke lokasi baru, jadi mereka tidak diinginkan untuk konten baru.
Buat salinan file i18n/en.toml untuk bahasa Anda. Misalnya, Anda akan menyalin i18n/en.toml ke i18n/fr.toml jika Anda melakukan terjemahan bahasa Prancis. File ini berisi teks yang ditampilkan oleh infrastruktur situs untuk hal -hal seperti menu, dan materi standar lainnya.
Edit file hugo.toml untuk mendaftar bahasa baru Anda. Cari entri [languages] dan cukup tambahkan entri baru. Ini memberi tahu generator situs Hugo untuk memproses konten Anda.
Edit scripts/lint_site.sh dan cari check_content . Tambahkan panggilan lain ke check_content untuk direktori konten baru Anda. Ini memastikan bahwa aturan berbunyi berlaku untuk konten baru Anda.
Edit file src/ts/lang.ts dan tambahkan bahasa baru Anda. Ini akan menambah bahasa Anda ke tombol sakelar bahasa yang tersedia di pendahuluan.istio.io dan akan membuatnya sehingga bahasa Anda akan didukung di menu pemilihan bahasa.
Dapatkan administrator ISTIO GITHUB untuk membuat tim pemelihara baru untuk bahasa Anda. Untuk bahasa Prancis, ini akan menjadi WG - Docs Maintainers/French .
Edit file CODEOWNERS dan tambahkan entri untuk bahasa Anda untuk memberikan tim baru yang telah Anda buat kepemilikan atas konten yang diterjemahkan dan file tabel terjemahan.
Anda kemudian dapat melakukan semua perubahan ini dan Anda dapat mulai menerjemahkan konten dan file terjemahan dengan cara yang murni bertahap. Saat Anda membangun situs, Anda akan menemukan konten Anda di <url>/<language code> . Misalnya, setelah Anda memeriksa semuanya, Anda harus dapat mencapai konten Anda di https://preliminary.istio.io/fr jika Anda melakukan terjemahan bahasa Prancis.
Setelah terjemahan Anda selesai dan Anda siap menerbitkannya ke dunia, ada beberapa perubahan lain yang perlu Anda buat:
Edit layouts/index.redir . Cari translated sites dan tambahkan baris untuk bahasa Anda. Ini akan menyebabkan pengguna datang ke situs untuk pertama kalinya secara otomatis dialihkan ke konten yang diterjemahkan yang cocok untuk mereka. Untuk bahasa Prancis, ini akan menjadi:
/ /fr 302 Language=fr
Edit layouts/partials/headers.html . Cari switch-lang dan Anda akan menemukan definisi untuk menu pemilihan bahasa. Tambahkan baris untuk bahasa baru Anda.
Dan itu saja.
Kami memiliki sejumlah cek di tempat untuk memastikan sejumlah invarian dipertahankan untuk membantu kualitas keseluruhan situs. Misalnya, kami melarang memeriksa tautan yang rusak dan kami melakukan pemeriksaan ejaan. Ada beberapa hal yang sulit untuk diperiksa secara sistematis melalui otomatisasi dan sebaliknya membutuhkan manusia untuk ditinjau dalam beberapa saat untuk memastikan semuanya baik -baik saja.
Ide yang bagus untuk menjalankan daftar ini sebelum setiap rilis utama situs:
Pastikan bahwa referensi ke Repo ISTIO di GitHub Don't Hardcode Branch Names. Cari semua penggunaan /release-1 atau /master di seluruh file markdown dan ganti yang dengan {{<source_branch_name>}} sebagai gantinya, yang menghasilkan nama cabang yang sesuai versi.
Tinjau file .spelling untuk kata -kata yang seharusnya tidak ada di sana. Ketik nama khususnya cenderung merayap di sini. Ketik nama tidak boleh ada di kamus dan sebaliknya harus ditampilkan dengan backticks . Hapus entri dari kamus dan perbaiki kesalahan pemeriksaan ejaan yang muncul.
Pastikan kapitalisasi yang tepat. Judul dokumen harus dikapitalisasi penuh (misalnya "Ini adalah judul yang valid"), sedangkan judul bagian harus menggunakan huruf kapitalisasi pertama saja (misalnya "ini adalah judul yang valid").
Pastikan blok teks yang diformat sebelumnya yang referensi file dari ISTIO GITHUB Repo gunakan @@ sintaks untuk menghasilkan tautan ke konten. Lihat di sini untuk konteks.
