zulip terminal
Zulip Terminal 0.7.0
التغييرات الحديثة | التكوين | مفاتيح ساخنة | الأسئلة الشائعة | التنمية | درس تعليمي
Zulip Terminal هو العميل الطرفي الرسمي لـ Zulip ، حيث يوفر واجهة مستخدم قائمة على النص (TUI).
الأهداف المحددة تشمل:
تعلم كيفية استخدام محطة Zulip مع البرنامج التعليمي لدينا.
نحن نعتبر العميل بالفعل تقديم تجربة مستخدمة معتدلة إلى حد ما.
ينصب تركيز التطوير الحالي على تحسين جوانب الاستخدام اليومي والتي يتم استخدامها بشكل أكثر شيوعًا - لتقليل الحاجة للمستخدمين للتبديل مؤقتًا إلى عميل آخر للحصول على ميزة معينة.
تشمل القيود الحالية التي نتوقع حلها فقط على المدى الطويل دعم:
لدى عميل الطرفية حاليًا عددًا من الاختلافات المتعمدة لعميل ويب Zulip:
للاستعلامات حول دعم الميزات المفقودة ، يرجى إلقاء نظرة على الأسئلة المتكررة (الأسئلة الشائعة) أو مشكلاتنا المفتوحة أو الدردشة مع المستخدمين والمطورين عبر الإنترنت في خادم Zulip Community Server!
نوصي بالتثبيت في بيئة افتراضية بيثون مخصصة (انظر أدناه) أو باستخدام خيار آلي مثل PIPX
الإصدارات المستقرة - هذه متوفرة على PYPI مثل الحزمة Zulip -MIND
للتثبيت ، قم بتشغيل أمر مثل: pip3 install zulip-term
أحدث إصدارات (GIT) - يمكن تثبيت أحدث إصدار تطوير من فرع مستودع GIT main
للتثبيت ، قم بتشغيل أمر مثل: pip3 install git+https://github.com/zulip/zulip-terminal.git@main
نحن نقدم أيضًا بعض عينة Dockerfiles لإنشاء صور Docker في Docker/.
مع Python 3.6+ المطلوب للتشغيل ، يجب أن يعمل ما يلي على معظم الأنظمة:
python3 -m venv zt_venv (يخلق بيئة افتراضية تسمى zt_venv في الدليل الحالي)source zt_venv/bin/activate (ينشط البيئة الافتراضية ؛ وهذا يفترض قذيفة تشبه باش) إذا قمت بفتح نافذة طرفية مختلفة (أو تسجيل الخروج/إعادة تشغيل جهاز الكمبيوتر الخاص بك) ، فستحتاج إلى تشغيل الخطوة 2 من القائمة أعلاه مرة أخرى قبل تشغيل zulip-term ، لأن ذلك ينشط تلك البيئة الافتراضية. يمكنك قراءة المزيد حول البيئات الافتراضية في وثائق Python 3 Library VenV.
لاحظ أنه لا يوجد نظام تحديث تلقائي ، لذا يرجى تتبع مواقع التحديث ذات الصلة بإصدار التثبيت الخاص بك:
إصدارات مستقرة
قبل الترقية ، نوصيك بالتحقق من التغييرات في الإصدارات الحديثة حتى تكون على دراية بأي تغييرات مهمة بين الإصدارات.
تم الإعلان عنها الآن في موضوع الإعلان عن # ANOUNCE> TERMINAL على خادم مجتمع Zulip (https://chat.zulip.org) ، وهو مرئي بدون حساب.
إذا كنت ترغب في تلقي رسائل بريد إلكتروني عند الإعلان عن التحديثات ، فأنت مرحب بك للتسجيل للحصول على حساب على هذا الخادم ، مما سيمكنك من تمكين إشعارات البريد الإلكتروني لدفق #Announce (مقالة المساعدة ، إعدادات الإشعارات على chat.zulip.org).
يمكنك أيضًا تخصيص إعداد مراقبة GitHub على صفحة المشروع لتضمين الإصدارات.
يوفر PYPI موجز إصدار RSS ، وتتبع العديد من الخدمات الأخرى هذه المعلومات.
أحدث إصدارات (GIT)
لن يتم تحديث الإصدارات المثبتة من فرع GIT main تلقائيًا - يشير "الأحدث" إلى الحالة عند نقطة التثبيت.
ينطبق هذا أيضًا على تثبيتات المصدر أو التطوير الأخرى (على سبيل المثال ، https://aur.archlinux.org/packages/python-zulip-term-git/).
لذلك ، قم بترقية الحزمة الخاصة بك باستخدام الأمر أعلاه ، أو واحدة ذات صلة بنظام الحزمة الخاص بك (مثل القوس).
على الرغم من أن الفرع main يهدف إلى البقاء مستقرًا ، إذا كان الترقية بين إصدارات "أحدث" تعسفي ، يرجى العلم بأن التغييرات لا يتم تلخيصها ، على الرغم من أن سجل الالتزام الخاص بنا يمكن قراءته للغاية.
عند تشغيل zulip-term أولاً ، يبحث عن ملف zuliprc ، افتراضيًا في الدليل المنزلي الخاص بك ، والذي يحتوي على التفاصيل لتسجيل الدخول إلى خادم zulip.
إذا لم يجد هذا الملف ، فلديك خياران:
سوف يطالبك zulip-term بالخادم والبريد الإلكتروني وكلمة المرور الخاصة بك ، وإنشاء ملف zuliprc لك في هذا الموقع
ملاحظة: إذا كنت تستخدم Google أو Github أو مصادقة خارجية أخرى للوصول إلى مؤسسة Zulip الخاصة بك ، فمن المحتمل ألا يكون لديك مجموعة كلمة مرور وتحتاج حاليًا إلى إنشاء واحدة لاستخدام Zulip-Terminal.
<Zulip server URL>/accounts/password/reset/ لإنشاء كلمة مرور جديدة لحسابك (على سبيل المثال: https://chat.zulip.org/accounts/spassword/reset/). في كل مرة تقوم فيها بتشغيل zulip-term ، يمكنك تحديد المسار إلى ملف zuliprc بديل باستخدام خيارات -c أو-- --config-file ، على سبيل المثال. $ zulip-term -c /path/to/zuliprc
يمكن تنزيل ملف .zuliprc المقابل لحسابك على خادم Zulip معين عبر تطبيقات الويب أو سطح المكتب المتصل بهذا الخادم. في الإصدارات الحديثة ، يمكن العثور على هذا في إعداداتك الشخصية في قسم الحساب والخصوصية ، ضمن مفتاح API باسم "عرض/تغيير مفتاح API الخاص بك".
إذا كان هذا هو حساب Zulip الوحيد الخاص بك ، فقد ترغب في نقل هذا الملف وإعادة تسميته إلى موقع الملف الافتراضي أعلاه ، أو إعادة تسميته إلى شيء لا يُنسى بحيث يمكنك نقله إلى خيار ---config-file . يمنحك ملف .zuliprc جميع الأذونات التي لديك كمستخدم.
يمكن تنزيل .zuliprc files مماثلة من قسم Bots لأي روبوتات قمت بإعداده ، على الرغم من أذونات محدودة في المقابل.
ملاحظة: إذا كان الخادم الخاص بك يستخدم شهادات موقعة ذاتيا أو اتصال غير آمن ، فستحتاج إلى إضافة خيارات إضافية إلى ملف zuliprc يدويًا - راجع الوثائق الخاصة بوحدة Zulip Python.
نقترح تشغيل zulip-term باستخدام خيار -e أو --explore (في وضع الاستكشاف) عندما تحاول محطة Zulip لأول مرة ، حيث لا نضع علامة على الرسائل على أنها قراءة. حاول المتابعة مع البرنامج التعليمي لدينا للحصول على تعليق الأشياء.
يحتوي ملف zuliprc على قسمين:
[api] مع المعلومات المطلوبة للاتصال بخادم Zulip الخاص بك[zterm] مع التكوين الخاص بـ zulip-term يمكن إنشاء ملف يحتوي على القسم الأول فقط تلقائيًا في بعض الحالات بواسطة zulip-term ، أو يمكنك تنزيل واحد من حسابك على الخادم الخاص بك (انظر أعلاه). يمكن إضافة أجزاء من القسم الثاني وتعديله على مراحل عندما ترغب في تخصيص سلوك zulip-term .
يمثل المثال أدناه ، مع محتويات قسم Dummy [api] ، ملف تكوين عمل مع جميع قيم [zterm] المتوافقة الافتراضية غير معلنة ومع الملاحظات المصاحبة:
[api]
[email protected]
key=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
site=https://example.zulipchat.com
[zterm]
## Theme: available themes can be found by running `zulip-term --list-themes`, or in docs/FAQ.md
theme=zt_dark
## Autohide: set to 'autohide' to hide the left & right panels except when they're focused
autohide=no_autohide
## Exit Confirmation: set to 'disabled' to exit directly with no warning popup first
exit_confirmation=enabled
## Footlinks: set to 'disabled' to hide footlinks; 'enabled' will show the first 3 per message
## For more flexibility, comment-out this value, and un-comment maximum-footlinks below
footlinks=enabled
## Maximum-footlinks: set to any value 0 or greater, to limit footlinks shown per message
# maximum-footlinks=3
## Notify: set to 'enabled' to display notifications (see elsewhere for configuration notes)
notify=disabled
## Color-depth: set to one of 1 (for monochrome), 16, 256, or 24bit
color-depth=256
## Transparency: set to 'enabled' to allow background transparency
## This is highly dependent on a suitable terminal emulator, and support in the selected theme
## Terminal emulators without this feature may show an arbitrary solid background color
transparency=disabled
## Editor: set external editor command, to edit message content
## If not set, this falls back to the $ZULIP_EDITOR_COMMAND then $EDITOR environment variables
# editor: nano
ملاحظة: قد يتم تحديد معظم إعدادات التكوين هذه على سطر الأوامر عند بدء تشغيل
zulip-term؛zulip-term -hأوzulip-term --helpقائمة كاملة بالخيارات.
لاحظ أن الإخطارات لا يتم دعمها حاليًا على WSL ؛ انظر #767.
يقوم الأمر التالي بتثبيت notify-send على الأنظمة المستندة إلى Debian ، ويمكن العثور على أوامر مماثلة لأنظمة Linux الأخرى أيضًا.
sudo apt-get install libnotify-bin
لا يلزم وجود حزمة إضافية لتمكين الإخطارات في OS X. ومع ذلك ، فإن الحصول على صوت للإخطار ، قم بتعيين المتغير التالي (استنادًا إلى نوع Shell). يمكن أن تكون قيمة الصوت (هنا ping) أي من ملفات .aiff الموجودة في /System/Library/Sounds أو ~/Library/Sounds .
سحق
echo 'export ZT_NOTIFICATION_SOUND=Ping' >> ~/.bash_profile
source ~/.bash_profile
Zsh
echo 'export ZT_NOTIFICATION_SOUND=Ping' >> ~/.zshenv
source ~/.zshenv
تتيح Zulip Terminal للمستخدمين نسخ نصوص معينة إلى الحافظة عبر وحدة Python ، Pyperclip . تستفيد هذه الوحدة من حزم النظام المختلفة التي قد تأتي أو لا تأتي مع نظام التشغيل. تتوفر ميزة "النسخ إلى الحافظة إلى الحافظة" حاليًا فقط لنسخ البريد الإلكتروني للبث ، من المنبثقة معلومات الدفق.
على Linux ، تستخدم هذه الوحدة أوامر xclip أو xsel ، والتي يجب أن تأتي بالفعل مع نظام التشغيل. إذا لم يتم تثبيت أي من هذه الأوامر على نظامك ، فقم بتثبيت أي شخص يستخدم:
sudo apt-get install xclip [Recommended]
أو
sudo apt-get install xsel
لا يلزم وجود حزمة إضافية لتمكين النسخ إلى الحافظة.
بينما تم تصميم Terminal Zulip للعمل مع أي خادم Zulip ، فإن المساهمين الرئيسيين موجودون على خادم Zulip Community على https://chat.zulip.org ، مع معظم المحادثة في تيار Zulip-terminal .
نرحب بك لعرض المحادثات في هذا الدفق باستخدام الرابط أعلاه ، أو الاشتراك في حساب ودردشة معنا - سواء كنت مستخدمًا أو مطورًا!
نحن نهدف إلى الحفاظ على Zulip Community Friendly ، والترحيب والإنتاجية ، لذلك إذا شاركت ، فيرجى احترام معايير مجتمعنا.
هذه مجموعة فرعية من معايير المجتمع المرتبطة أعلاه ، والتي تكون أكثر صلة بمستخدمي محطة Zulip: أولئك الذين من المحتمل أن يكونوا في بيئة نصية ، ومحدودة في صفوف/أعمدة الأحرف ، وهم موجودون في هذا الدفق الأصغر.
تفضل النص في كتل التعليمات البرمجية ، بدلاً من لقطات الشاشة
يدعم Zulip Terminal تنزيل الصور ، ولكن ليس هناك ما يضمن أن يكون المستخدمون قادرين على عرضها.
جرب Meta + M لرؤية مثال تنسيق محتوى ، بما في ذلك كتل التعليمات البرمجية
تفضل الإشارات الصامتة على الإشارات العادية - أو تجنب الإشارات بالكامل
مع موضوعات Zulip ، يمكن أن يكون المستلم المقصود في كثير من الأحيان واضحًا بالفعل. سيكون الأعضاء ذوي الخبرة حاضرين حسب وقت تصاريحهم - الاستجابة للرسائل عند عودتهم - وقد يتمكن الآخرون من المساعدة قبل ذلك.
(حفظ الإشارات المنتظمة لأولئك الذين لا تتوقع أن تكون حاضرا على أساس منتظم)
جرب Ctrl + F / B للتنقل من خلال الإكمال التلقائي في محتوى الرسائل ، بعد كتابة @_ لتحديد ذكر صامت
تفضل تقليم الاقتباس والرد على النص على الأجزاء ذات الصلة فقط من الرسائل الطويلة - أو تجنب الاقتباس بالكامل
غالبًا ما توضح موضوعات Zulip الرسالة التي ترد عليها. قد يكون من الصعب قراءة الرسائل الطويلة مع صفوف وأعمدة محدودة من النص ، ولكن يتم تفاقم ذلك إذا اقتبس رسالة طويلة كاملة مع محتوى إضافي.
جرب > لاقتباس رسالة محددة ، حذف النص كالمعتاد عند إنشاء رسالة
تفضل رد فعل رموز تعبيرية سريعة لإظهار الاتفاق بدلاً من الرسائل القصيرة البسيطة
تشغل ردود الفعل مساحة أقل ، بما في ذلك في محطة Zulip ، وخاصة عندما يرغب العديد من المستخدمين في الاستجابة بنفس المشاعر.
حاول + لتبديل الإبهام (+1) على رسالة ، أو استخدم : للبحث عن ردود فعل أخرى
يتم بناء محطة Zulip من قبل مجتمع Zulip الرائع.
لكي تكون جزءًا منه وللمساهمة في الكود ، لا تتردد في العمل على أي مشكلة أو اقتراح فكرتك على #Zulip-terminal.
للالتزام هيكل وأسلوب ، يرجى مراجعة قسم نمط الالتزام أدناه.
إذا كنت جديدًا على git (أو لا!) ، فقد تستفيد من دليل Zulip Git. عند المساهمة ، من المهم أن نلاحظ أننا نستخدم سير عمل موجه نحو Rebase .
يتوفر برنامج تعليمي بسيط لتنفيذ مؤشر typing . اتبعه لفهم كيفية تنفيذ ميزة جديدة لـ Zulip-terminal.
يمكنك بالطبع تصفح المصدر على Github وفي شجرة المصدر التي تقوم بتنزيلها ، والتحقق من نظرة عامة على الملف المصدر لأفكار حول كيفية ترتيب الملفات حاليًا.
يستخدم Zulip Terminal URWID لتقديم مكونات واجهة المستخدم في المحطة. Urwid هي مكتبة رائعة يمكنك من خلالها تقديم واجهة مستخدم طرفية لائقة فقط باستخدام Python. يعد تعليمي Urwid مكانًا رائعًا للبدء للمساهمين الجدد.
أولاً ، شوكة مستودع zulip/zulip-terminal على github (انظر كيف) ثم استنساخ مستودعك المتشعب محليًا ، ليحل محل اسم _ username الخاص بك باسم مستخدم github:
$ git clone --config pull.rebase [email protected]:YOUR_USERNAME/zulip-terminal.git
يجب أن ينشئ هذا دليلًا جديدًا للمستودع في الدليل الحالي ، لذلك أدخل دليل المستودع مع cd zulip-terminal وتكوين وجلب المستودع عن بُعد المنبع لشوكة Zulip الخاصة بك المنسخ:
$ git remote add -f upstream https://github.com/zulip/zulip-terminal.git
للحصول على شرح مفصل على الأوامر المستخدمة للاستنساخ وإعداد Upstream ، راجع الخطوة 1 من قسم Get Zulip Code في دليل GIT الخاص بـ Zulip.
خيارات مختلفة متوفرة ؛ نحن نستكشف فوائد كل منها وسنقدر التعليقات التي تستخدمها أو تشعر بها بشكل أفضل.
لاحظ أن الأدوات المستخدمة في كل حالة عادة ما تكون متماثلة ، ولكن يتم استدعاؤها بطرق مختلفة.
يجب تشغيل الأوامر التالية في دليل المستودع ، الذي تم إنشاؤه بواسطة عملية مماثلة لتلك الموجودة في القسم السابق.
$ pip3 install --user pipenv
--python 3.6 ليكون أكثر تحديداً) $ pipenv --three
$ pipenv install --dev
$ pipenv run pip3 install -e '.[dev]'
$ pipenv run gitlint install-hook
إنشاء وتنشيط بيئة افتراضية يدويًا ؛ يجب أن تعمل أي طريقة ، مثل تلك المستخدمة في التثبيت البسيط أعلاه
python3 -m venv zt_venv (ينشئ VenV اسمه zt_venv في الدليل الحالي)source zt_venv/bin/activate (ينشط venv ؛ هذا يفترض قذيفة تشبه باش)قم بتثبيت Zulip-MIND ، مع متطلبات التطوير
$ pip3 install -e '.[dev]'
$ gitlint install-hook
هذا هو أحدث وأبسط النهج ، إذا كنت قد make تثبيتها:
make (إعداد بيئة افتراضية مثبتة في zt_venv في الدليل الحالي)source zt_venv/bin/activate (ينشط venv ؛ هذا يفترض قذيفة تشبه باش)gitlint install-hook (قم بتوصيل خطاف Gitlint Complish-Message)بمجرد إعداد بيئة تطوير ، قد تجد ما يلي مفيدًا ، اعتمادًا على نوع البيئة الخاص بك:
| مهمة | Make & Pip | pipenv |
|---|---|---|
| تشغيل بشكل طبيعي | zulip-term | pipenv run zulip-term |
| تشغيل في وضع التصحيح | zulip-term -d | pipenv run zulip-term -d |
| ركض مع التنميط | zulip-term --profile | pipenv run zulip-term --profile |
| تشغيل جميع المبيدات | ./tools/lint-all | pipenv run ./tools/lint-all |
| تشغيل جميع الاختبارات | pytest | pipenv run pytest |
| بناء تقرير تغطية اختبار | pytest --cov-report html:cov_html --cov=./ | pipenv run pytest --cov-report html:cov_html --cov=./ |
إذا كان استخدام Make with PIP ، فسيضمن تشغيل make أن بيئة التطوير محدثة مع التبعيات المحددة ، وهي مفيدة بعد الجلب من GIT وإعادة الترجيح.
اختر محرر النص المفضل لديك أو بيئة التطوير!
يتضمن المصدر ملف .editorconfig الذي يمكّن العديد من المحررين من تكوين أنفسهم تلقائيًا لإنتاج ملفات تلبي الحد الأدنى من متطلبات المشروع. انظر https://editorconfig.org لدعم المحرر ؛ لاحظ أن البعض قد يتطلب الإضافات إذا كنت ترغب في استخدام هذه الميزة.
يتم تلقائيًا يتم تشغيل المبيدات والاختبارات الآلية (PYTEST) تلقائيًا في CI (إجراءات github) عند إرسال طلب سحب (PR) ، أو دفع التغييرات إلى طلب سحب موجود.
ومع ذلك ، يمكن أن يؤدي تشغيل هذه الشيكات على جهاز الكمبيوتر إلى تسريع تطورك عن طريق تجنب الحاجة إلى دفع الكود الخاص بك بشكل متكرر إلى GitHub. يتم سرد الأوامر لتحقيق ذلك في جدول مهام التطوير أعلاه (قد يتم أيضًا تشغيل المبيدات الفردية عبر البرامج النصية في tools/ ).
بالإضافة إلى ذلك ، إذا كنت تستخدم نظامًا قائمًا على make :
make lint make test كل مجموعة من المهامmake check جميع عمليات الفحص ، وهو أمر مفيد قبل دفع العلاقات العامة (أو تحديث)make check tools/check-branchملاحظة: من غير المرجح أن يتم دمج طلب سحب ، حتى تمر جميع المبيدات والاختبارات ، بما في ذلك على أساس لكل تلوين.
يتطلب تصحيح بعض الأخطاء المخلوطة التدخل اليدوي ، كما هو الحال من mypy لتحقيق النوع.
للحصول على نصائح حول الاختبار ، يرجى مراجعة القسم أدناه فيما يتعلق باختبار.
ومع ذلك ، قد يتم إصلاح أخطاء الاصطدام الأخرى تلقائيًا ، كما هو موضح أدناه - هذا يمكن أن يوفر الكثير من الوقت يدويًا يدويًا لضبط الكود الخاص بك لتمرير البياضات!
إذا كانت لديك مشاكل في فهم سبب فشل المبيدات أو الاختبار ، فيرجى دفع الكود الخاص بك إلى فرع/علاقات عامة ويمكننا مناقشة المشكلات في العلاقات العامة أو على chat.zulip.org.
إذا قمت بتحديث هذه ، لاحظ أنك لا تحتاج إلى تحديث النص في كلا المكانين يدويًا لتمرير Linting.
مصدر الحقيقة في الكود المصدري ، لذلك ببساطة تحديث ملف Python وتشغيل الأداة ذات الصلة. حاليا لدينا:
tools/lint-hotkeys --fix لتجديد المستندات/hotkeys.md من config/keys.pytools/lint-docstring --fix لتجديد المستندات/ملف المطور(يتم استخدام هذه الأدوات أيضًا لعملية Linting ، لضمان مزامنة هذه الملفات)
يستخدم المشروع black و isort لفرز التصنيف على غرار الكود والاستيراد على التوالي.
يمكن تشغيل هذه الأدوات كبيانات محليًا ، ولكن يمكن أيضًا تنسيق الكود الخاص بك تلقائيًا .
إذا كنت تستخدم إعدادًا قائمًا على make ، فسيقوم Running make fix بتشغيل كلاهما (وبعض الأدوات الأخرى) وإعادة تنسيق الحالة الحالية للرمز الخاص بك -لذلك سترغب في الالتزام أولاً فقط في حالة ، ثم --amend هذا الالتزام إذا كنت سعيدًا بالتغييرات.
يمكنك أيضًا استخدام الأدوات بشكل فردي على ملف أو دليل ، على سبيل المثال. اختبارات black zulipterminal أو isort tests/model/test_model.py
أثناء عملك محليًا ، والتحقيق في التغييرات التي يجب إجراؤها ، من الشائع إنشاء سلسلة من الالتزامات الصغيرة لتخزين تقدمك. في كثير من الأحيان يمكن أن يشمل ذلك ارتكابًا تصلح مشكلات الاختبار أو الاختبار في الالتزام (الالتزام) السابق. هذه هي ارتباطات على الطراز التنموي - ومن المرجح أن يكتب الجميع تقريبًا في هذا النمط إلى حد ما.
يرتكب النمط التنموي يخزن التغييرات بشكل جيد بالنسبة لك الآن. ومع ذلك ، عند مشاركة التعليمات البرمجية الخاصة بك ، يعد ارتكاب الرسائل مكانًا رائعًا للتواصل مع الآخرين بما تتغير فيه ولماذا. يمكن أن يجعل ترتيب الهيكل أيضًا أسهل وأسرع للقارئ لفهم التغييرات ، وأن تحترم وقتهم. أحد الأمثلة على ذلك هو أن الفردية الكبيرة جدًا يمكن أن تستغرق الكثير من الوقت للمراجعة ، مقارنة بما إذا كانت تقسيمها. آخر هو إذا قمت بإصلاح الاختبارات/الالتزام: أي التزام (أو يرتكب!) يقوم بهذا الإصلاح ، وإذا كان في نفس الفرع/العلاقات العامة ، فلماذا لم يتم إصلاح الالتزام الأصلي بدلاً من ذلك؟
لذلك ، عند إنشاء طلب سحب (PR) ، يرجى مراعاة أن الكود الخاص بك أكثر عرضة للاندماج ، بسرعة أكبر ، إذا كان من الأسهل قراءة وفهم ومراجعة - وجزء كبير من ذلك هو كيف تقوم ببناء التغييرات الخاصة بك على الالتزامات ، ووصف تلك التغييرات في الالتزام.
لكي تكون مثمرًا وجعل من السهل على PRS مراجعة وتحديثك ، نتبع نهجًا تم اتباعه في Zulip وأماكن أخرى ، بهدف أن يتكون PRS من سلسلة من الارتباطات المتماسكة الحد الأدنى :
لاحظ أن الاحتفاظ بهذه المبادئ يمكن أن يعطي فوائد أخرى ، قبل وأثناء وبعد مراجعة العلاقات العامة ، بما في ذلك:
git bisect في فرعك أو بشكل main نحن الآن نفرض جانبًا محدودًا من الطبيعة المتماسكة للالتزامات في العلاقات العامة في وظيفة كجزء من تكاملنا المستمر (CI) ، ضمان ارتباط العلاقات العامة المعزولة ، والتي تعمل بشكل أساسي make check كل التزام في فرعك. يمكنك تكرار ذلك محليًا قبل الدفع إلى github باستخدام tools/check-branch .
على الرغم من أن PRS الصغيرة أو إثبات المفهوم أمر جيد في البداية للدفع كما هي ، فمن المحتمل أن تتم مراجعتها فقط بناءً على التغييرات الإجمالية. بشكل عام ، إذا بدا الالتزامات الفرد أن لديهم نمطًا تنمويًا ، فمن المحتمل أن يقدم المراجعون ردود فعل أقل محددة ، ومن المؤكد أن يتم طلب الالتزامات المتماسكة الحد الأدنى قبل الاندماج.
أوامر إعادة الهيكلة - تعتمد معظم إعادة الهيكلة على إعادة git rebase -i upstream/main التفاعلي (على سبيل المثال
المراجعة الذاتية - هناك نهج آخر مفيد هو مراجعة ارتباطاتك محليًا (انظر اقتراحات Zulip) وبعد الضغط على Github. يتيح لك ذلك فحص أي شيء يبدو في غير مكانه وإصلاحه ، والذي من المحتمل أن يلتقطه شخص ما في مراجعته ، مما يساعد على أن تكون عمليات التقديم الخاصة بك أكثر تلميعًا ، وكذلك تشير مرة أخرى إلى احترام وقت المراجعين.
نهدف إلى اتباع أسلوب الالتزام القياسي للحفاظ على git log متسقًا وسهل القراءة.
يشبه إلى حد كبير العمل مع التعليمات البرمجية ، نقترح عليك الرجوع إلى الالتزامات الحديثة في سجل GIT ، لأمثلة على الأسلوب الذي نستخدمه بنشاط.
يتبع أسلوبنا العام لالتزام رسائل الإرشادات العامة الممنوحة لرسائل الالتزام Zulip ، لذلك نوصي بقراءة ذلك أولاً.
ألقاب التزامنا (الملخصات) لها اختلافات طفيفة من نمط الزوليب العام ، مع كل:
/Tests updated أو Tests added في نص الالتزام)refactor: ، bugfix: requirements: (انظر أدناه)بعض الأمثلة تلتزم عناوين: (من الناحية المثالية أكثر وصفية في الممارسة!)
file3/file1/file2: Improve behavior of something.file1.txt و file2.py و file3.mdrefactor: file1/file2: Extract some common function.file1.py و file2.pybugfix: file1: Avoid some noticeable bug.file1.pytests: file1: Improve test for something.file1 ، على الأرجح في test_file1.pyrequirements: Upgrade some-dependency from ==9.2 to ==9.3. للمساعدة في تلبية بعض هذه القواعد ، يمكنك استخدام GitLint ، كما هو موضح في القسم التالي.
ومع ذلك ، يرجى التحقق من ارتكابك يدويًا مقابل قواعد الأناقة هذه ، نظرًا لأن Gitlint لا يمكنها التحقق من كل شيء - بما في ذلك اللغة أو القواعد!
يتم تثبيت أداة gitlint افتراضيًا في بيئة التطوير ، ويمكن أن تساعد في ضمان تلبية ارتباطاتك بالمعايير المتوقعة.
يمكن للأداة التحقق من ارتباطات محددة يدويًا ، على سبيل المثال. gitlint لأحدث الالتزام ، أو gitlint --commits main.. للالتزامات المؤدية من main . ومع ذلك ، فإننا نوصي بشدة بتشغيل gitlint install-hook لتثبيت خطاف gitlint Message (أو pipenv run gitlint install-hook مع إعدادات pipenv).
إذا تم تثبيت الخطاف كما هو موضح أعلاه ، ثم بعد الانتهاء من النص للالتزام ، سيتم فحصه بواسطة Gitlint مقابل النمط الذي أنشأناه ، وسيقدم المشورة إذا كانت هناك أي مشكلات تلاحظها. إذا وجد Gitlint أيًا ، فسيسأل عما إذا كنت ترغب في الالتزام بالرسالة كما هي ( y لـ "نعم") ، أو أوقف عملية الالتزام ( n لـ "no") ، أو تحرير رسالة الالتزام ( e لـ "Edit").
على الرغم من أن المحتوى لا يزال يعتمد على مهاراتك في الكتابة ، فإن هذا يضمن بنية تنسيق أكثر اتساقًا بين الالتزامات ، بما في ذلك المؤلفين المختلفين.
تتم كتابة اختبارات zulip-terminal باستخدام pytest. يمكنك قراءة الاختبارات في مجلد /tests للتعرف على اختبارات كتابة فئة /وظيفة جديدة. إذا كنت جديدًا على Pytest ، فمن الموصى بالتأكيد بقراءة وثائقها.
لدينا حاليًا الآلاف من الاختبارات التي يتم فحصها عند تشغيل pytest . على الرغم من أنه يعتمد على قدرة النظام الخاصة بك ، إلا أن هذا يجب أن يستغرق عادة أقل من دقيقة واحدة للتشغيل. ومع ذلك ، أثناء تصحيح الأخطاء ، قد لا تزال ترغب في الحد من نطاق الاختبارات الخاصة بك ، لتحسين وقت التحول:
إذا فشلت الكثير من الاختبارات بطريقة مطوّلة للغاية ، فقد تجرب خيار -x (على سبيل المثال. pytest -x ) لإيقاف الاختبارات بعد الفشل الأول ؛ نظرًا لتصوير الاختبارات وتركيبات الاختبار ، يمكن حل العديد من الأخطاء/الفشل الظاهرة مع إصلاح واحد فقط! ( pytest --maxfail 3 على سبيل المثال.
لتجنب إجراء جميع الاختبارات الناجحة في كل مرة ، إلى جانب الإخفاقات ، يمكنك الركض مع- --lf (على سبيل المثال- pytest --lf ) ، قصيرًا --last-failed (قد تكون خيارات مفيدة مشابهة --failed-first --new-first ، والتي قد تعمل بشكل جيد مع -x )
نظرًا لأن Pytest 3.10 موجود --sw ( --stepwise ) ، والذي يعمل من خلال حالات فشل معروفة بنفس الطريقة التي يمكن بها استخدام --lf و -x ، والتي يمكن دمجها مع --stepwise-skip للتحكم في الاختبار هو التركيز الحالي
إذا كنت تعرف أسماء الاختبارات التي تفشل و/أو في موقع معين ، فيمكنك تقييد الاختبارات على موقع معين (على سبيل المثال pytest tests/model ) أو استخدام كلمة رئيسية محددة (مثل pytest -k __handle )
عند تشغيل مجموعة فرعية فقط من الاختبارات ، يصبح الأمر أكثر عملية ومفيدة لاستخدام خيار -v ( --verbose ) ؛ بدلا من إظهار أ . (أو F ، E ، x ، etc) لكل نتيجة اختبار ، فإنه يعطي الاسم (مع المعلمات) لكل اختبار يجري تشغيله (مثل pytest -v -k __handle ). يُظهر هذا الخيار أيضًا مزيدًا من التفاصيل في الاختبارات ويمكن إعطاؤه عدة مرات (مثل pytest -vv ).
للحصول على مساعدة إضافية مع خيارات Pytest ، راجع pytest -h ، أو تحقق من وثائق Pytest الكاملة.
print يتم إعادة توجيه stdout (الإخراج القياسي) لـ zulip-terminal إلى ./debug.log إذا تم تمكين تصحيح الأخطاء في وقت التشغيل باستخدام -d أو-- --debug .
هذا يعني أنه إذا كنت ترغب في التحقق من قيمة المتغير ، أو ربما تشير إلى الوصول إلى نقطة معينة في الكود ، يمكنك ببساطة استخدام print() ، على سبيل المثال.
print ( f"Just about to do something with { variable } " ) وعند التشغيل مع خيار تصحيح الأخطاء ، سيتم طباعة السلسلة إلى ./debug.log .
مع محطة تشبه باش ، يمكنك تشغيل شيء مثل tail -f debug.log في محطة أخرى ، لرؤية الإخراج من print كما يحدث.
إذا كنت ترغب في تصحيح محطة Zulip-Terminal أثناء تشغيلها ، أو في حالة معينة ، يمكنك إدراج
from pudb . remote import set_trace
set_trace () في الجزء من الكود الذي تريد تصحيحه. سيبدأ هذا اتصال Telnet لك. يمكنك العثور على عنوان IP ومنفذ اتصال Telnet في ./debug.log . ثم ببساطة الجري
$ telnet 127.0.0.1 6899
في محطة أخرى ، حيث 127.0.0.1 هو عنوان IP و 6899 هو المنفذ الذي تجده في ./debug.log .
هذا يعني على الأرجح أنك قمت بتثبيت إصدارات طبيعية وتطوير من طرفية Zulip.
لضمان تشغيل نسخة التطوير:
في حالة استخدام PipenV ، اتصل بـ pipenv run zulip-term من دليل zulip-terminal المستنسخة/التي تم تنزيلها ؛
إذا كنت تستخدم PIP (PIP3) ، تأكد من تنشيط البيئة الافتراضية الصحيحة (VENV) ؛ اعتمادًا على كيفية تكوين قذيفك ، قد يظهر اسم VENV في موجه الأوامر. لاحظ أنه لا يتضمن إدراج -e في أمر PIP3 أيضًا هذه المشكلة.
