istio.io
1.0.0
| موقع | حالة |
|---|---|
| istio.io | |
| تمهيدي | |
| Archive.istio.io |
يحتوي هذا المستودع على الكود المصدري لـ iStio.io و Prelinary.istio.io.
يرجى الاطلاع على ملف ISTIO README الرئيسي للتعرف على مشروع ISTIO العام وكيفية الاتصال بنا. لمعرفة كيف يمكنك المساهمة في أي من مكونات ISTIO ، يرجى الاطلاع على إرشادات مساهمة ISTIO.
لمعرفة كيفية تحرير وإنشاء محتوى هذا الريبو ، يرجى الرجوع إلى إنشاء صفحات وتحريرها.
يحافظ ISTIO على اختلافين في موقعه العام.
iStio.io هو الموقع الرئيسي ، الذي يوضح وثائق للإصدار الحالي للمنتج. يحتوي iStio.io/archive على لقطات من الوثائق للإصدارات السابقة للمنتج. هذا مفيد للعملاء الذين لا يزالون يستخدمون هذه الإصدارات القديمة.
يحتوي prelimal.istio.io على الوثائق التي تم تحديثها بشكل نشط للإصدار التالي من المنتج.
يمكن للمستخدم التنقل بشكل تافهة بين الاختلافات المختلفة للموقع باستخدام قائمة الترس في أعلى يمين كل صفحة. يتم استضافة كلا الموقعين على NetLify.
تتمسك تغييرات الوثائق بشكل أساسي بالفرع الرئيسي لـ iStio.io. تنعكس التغييرات الملتزمة في هذا الفرع تلقائيًا في التمهيدي.
محتوى iStio.io مأخوذ من أحدث فرع الإصدار-xxx. يتم تحديد الفرع المحدد الذي يتم استخدامه بواسطة تكوين مشروع ISTIO.IO NetLify.
سيقوم التحقق من التحديثات إلى الفرع الرئيسي تلقائيًا بتحديث التمهيدي. Sistio.io ، وسيتم انعكاسه فقط في ISTIO.io في المرة التالية التي يتم فيها إنشاء الإصدار ، والذي يمكن أن يكون عدة أسابيع في المستقبل. إذا كنت ترغب في انعكاس بعض التغييرات على الفور على iStio.io ، فأنت بحاجة إلى التحقق من التغييرات الخاصة بك على الفرع الرئيسي وإلى فرع الإصدار الحالي (اسم release-<MAJOR>.<MINOR> مثل release-1.7 ).
يمكن الاعتناء بهذه العملية تلقائيًا عن طريق البنية التحتية لدينا. إذا قمت بتقديم العلاقات العامة إلى الفرع الرئيسي وتوضيح العلاقات العامة مع علامة cherrypick/release-<MAJOR>.<MINOR>
فيما يلي الخطوات اللازمة لإنشاء إصدار وثائق جديد. لنفترض أن الإصدار الحالي من ISTIO هو 1.6 وترغب في تقديم 1.7 والذي كان قيد التطوير.
تشغيل make prepare-1.7.0 ، وهذا كل شيء. سيحصل هذا على أحدث مستندات مرجعية من فرع مصدر ISTIO الجديد في مجلد content/en/docs/reference .
للتشغيل الجاف قبل الإصدار الرسمي ، قم make release-1.7.0-dry-run ، والذي سيقوم فقط بإنشاء release-1.7-dry-run ولا يلمس أي فروع أخرى.
في يوم الإصدار ، قم بتشغيل make release-1.7.0 . سيؤدي هذا إلى تغيير بعض المتغيرات في master and release-1.6 ، وإنشاء release-1.7 للإصدار الجديد.
انتقل إلى مشروع iStio.io على NetLify وافعل ما يلي:
قم بتغيير الفرع الذي تم تصميمه من فرع الإصدار السابق إلى فرع الإصدار الجديد ، في هذا release-1.7 (أو release-1.7-dry-run حسب الاقتضاء).
حدد خيار تشغيل إعادة البناء وإعادة النشر الفوري.
بمجرد الانتهاء من النشر ، استعرض istio.io وتأكد من أن كل شيء يبدو جيدًا.
انتقل إلى محرك بحث Google المخصص وافعل ما يلي:
قم بتنزيل ملف سياق iStio.io CSE من علامة التبويب المتقدمة.
أضف FacetItem جديد في الجزء العلوي من الملف الذي يحتوي على رقم إصدار الإصدار السابق. في هذه الحالة ، سيكون هذا V1.6 .
قم بتحميل ملف سياق CSE المحدث إلى الموقع.
في قسم الإعداد ، أضف موقعًا جديدًا يغطي دليل أرشيف الإصدار السابق. في هذه الحالة ، سيكون عنوان URL الموقع هو istio.io/v1.6/* . اضبط تسمية هذا الموقع على اسم عنصر الوجه الذي تم إنشاؤه أعلاه ( V1.6 في هذه الحالة).
قبل أيام قليلة من إصدار التصحيح ، يجب على مديري الإفراج إخطار Doc WG بأن الإصدار قد تم إنشاؤه وأنه يبدأ اختبار التأهيل طويل المدى. في هذا الوقت ، انقل اختبارات أتمتة DOC لاستخدام الإصدار الجديد للتحقق من تمريرات اختبار DOC الآلي.
للانتقال إلى إصدار جديد (تأكد من وجودك في فرع إصدار التصحيح):
تشغيل go get istio.io/istio@AXY && go mod tidy .
إنشاء PR مع 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 في الفرع master ، والذي سيعيد ترشيح release-1.6 واستبداله بالأرشيف السابق في الفرع master . إذا كان من الضروري أن ينعكس هذا التحديث في iStio.io ، فقد يتم اختيار العلاقات العامة إلى الفرع للإصدار current .
تحتوي تدفقات الإصدار بدءًا من release-1.6 على اختبارات لمحتوى الاختبار. كل اختبارات الإصدار مقابل إصدار/ارتكاب معين. عندما يكون لدى فريق الإصدار بناء ، 1.xy ، جاهز لاختباراتهم الطويلة ، يجب أن يأتي إلى فريق المستندات لإجراء اختبار لبدء تشغيل هذا الإصدار.
هناك نوعان من البناء ، public private . تم تصميم تصميمات DEV و READE العادية من repos العامة لدينا ولديها صور في مستودع يمكن الوصول إليه للجمهور ويعتبرون public . التصميمات Private هي تلك التي لا يمكننا الكشف عنها كثيرًا قبل الإصدار. عادةً ما يكون إشعارًا مسبقًا بأن الإصدار سيحدث في غضون أسبوعين لـ CVES. نظرًا لأننا لا نستطيع الكشف عن أي شيء قبل الإصدار الفعلي ، فإن المصدر والصور المبنية موجودة في repos الخاصة. نظرًا لأن المصدر والصور خاصة ، لا يمكننا الانتقال إليهم فعليًا حتى يتم إصدارها علنًا ، وبالتالي لا يوجد اختبار مبكر للإصدار في iStio.io. الفرق في التصميم private هو أن الصور التي نختبرها لم يتم إنشاؤها أبدًا في مستودع GCR.IO public ، لذلك في هذه الحالة ، نستخدم صور 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 ، سيكون المحور غير محصور.
أخيرًا ، قم بإنشاء العلاقات العامة وتقديمها مع التغييرات ويمكن للمرء رؤية نتائج الاختبار في العلاقات العامة. عادة ، لن يندمج العلاقات العامة فعليًا حتى يتم إصدار الإصدار (في بعض الأحيان هناك بنيات متعددة للإصدار).
توضح العديد من المستندات الموجودة على موقع ISTIO ميزات باستخدام الأوامر التي قد تستمر أو لا تستمر في العمل مع تطور ISTIO من الإصدار إلى الإصدار. لضمان بقاء الإرشادات الموثقة على اطلاع دائم بقدر القليل من الاختبارات اليدوية المستمرة قدر الإمكان ، أنشأنا إطار عمل لأتمتة اختبار هذه المستندات.
تتضمن كل صفحة على iStio.io التي يمكن اختبارها مؤشرا PAGE TEST تحت عنوان الصفحة. على سبيل المثال:
تشير علامة الاختيار الخضراء إلى أن الاختبار الآلي متاح للصفحة. الصفحة محدثة وتعمل كما هو موثق.
من ناحية أخرى ، يعني اللون الرمادي X أنه لا يوجد اختبار تلقائي متاح للصفحة ، حتى الآن. سنقدر ذلك إذا كنت ترغب في المساعدة في إنشاء واحدة! هدفنا هو في نهاية المطاف إجراء اختبار تلقائي لكل مستند قابل للاختبار المنشور على موقع ISTIO.
انظر الاختبارات ReadMe لمزيد من المعلومات.
يتم ترجمة الموقع إلى لغات متعددة. مصدر الحقيقة هو المحتوى الإنجليزي ، في حين أن اللغات الأخرى مشتقة وتميل إلى التخلف قليلاً. تحصل كل لغة موقع على دليل محتوى محتوى خاص به وملف جدول الترجمة. يتم تحديد اللغات باستخدام رمز اللغة الدولي المكون من حرفي. يقع محتوى الموقع الرئيسي في 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 وأضف لغتك الجديدة. سيؤدي ذلك إلى إضافة لغتك إلى زر تبديل اللغة المتاح على emorial.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 . ابحث عن switch-lang وستجد تعريفات قائمة اختيار اللغة. أضف خطًا للغة الجديدة.
وهذا كل شيء.
لدينا عدد من الشيكات في مكانها لضمان الحفاظ على عدد من الثنائيات من أجل مساعدة الجودة الإجمالية للموقع. على سبيل المثال ، نحن لا نمنع التحقق من الروابط المكسورة ونقوم بالتحقق الإملائي. هناك بعض الأشياء التي يصعب التحقق منها بشكل منهجي من خلال الأتمتة وبدلاً من ذلك تطلب من الإنسان مراجعتها منذ فترة لضمان كل شيء على ما يرام.
إنها لفكرة جيدة أن تمر عبر هذه القائمة قبل كل إصدار رئيسي للموقع:
تأكد من أن الإشارات إلى repos ISTIO على github لا تُحمل أسماء الفروع المتشددين. ابحث عن أي استخدامات من /release-1 أو /master خلال جميع ملفات Markdown واستبدلها باسم {<source_branch_name>}} بدلاً من ذلك ، والذي ينتج اسم فرع مناسب للإصدار.
راجع الملف .spelling للكلمات التي لا ينبغي أن تكون هناك. اكتب الأسماء على وجه الخصوص تميل إلى الزحف هنا. يجب ألا تكون الأسماء النوعية في القاموس ويجب أن تظهر بدلاً من ذلك مع backticks . قم بإزالة الإدخالات من القاموس وإصلاح أي أخطاء فحص إملائية تظهر.
ضمان الرسملة المناسبة. يجب أن تكون عناوين المستندات ذات رسملة كاملة (على سبيل المثال "هذا عنوان صالح") ، بينما يجب أن تستخدم عناوين القسم رسملة الحروف الأولى فقط (على سبيل المثال "هذا عنوان صالح").
تأكد من أن الكتل النصية المسبقة التي تشير إلى الملفات من repos istio github تستخدم بناء الجملة لإنتاج روابط للمحتوى. انظر هنا للسياق.
