فوضى مألوفة في أسماء ارتكابها. صورة مألوفة؟

بالتأكيد أنت تعرف بوابة التدفق . هذه مجموعة رائعة من الاصطلاحات المتفرعة في Git. إنه موثق جيدًا وموزع على نطاق واسع. عادة ما نكون على دراية بالفروع الصحيحة ونتحدث عن ذلك كثيرًا ، ولكن لسوء الحظ ، نولي القليل من الاهتمام لمسألة أوامر التسمية ، ولهذا السبب غالباً ما تتم كتابة الرسائل في Git بطريقة غير نظامية.

اسمي Yerzhan Tashbenbetov ، أعمل في أحد فرق Yandex.Market. واليوم سأخبر قرّاء هبر بالأدوات التي نستخدمها لإنشاء إلتزامات ذات معنى في الفريق. أدعوك للانضمام إلى المناقشة حول هذا الموضوع.

عدم وجود اتفاق على تسمية التسمية يجعل من الصعب العمل مع التاريخ في جيت. كان هذا في فريقنا. قبل استخدام القواعد العامة للجميع وتنفيذ الأتمتة ، تبدو الالتزامات النموذجية كما يلي:

SECRETMRKT-700:     , . SECRETMRKT-701, SECRETMRKT-702:     ...

أولاً ، كتب كل مطور الرسائل حسب رغبته: وصف أحدهم المهمة ، وسرد شخص ما التغييرات التي تم إجراؤها ، واستخدم شخص ما مولد عبارة عشوائية. كان كل شيء على خلاف. ثانياً ، غالبًا ما تقصر أرقام المهام التي كانت موجودة في ارتكاب نص مفيد. كل هذا جعل من الصعب العمل بفعالية مع التاريخ في جيت.

لهذا السبب ، قمنا بتطبيق معيار الالتزامات التقليدية في الفريق ، وبدأنا في إنشاء تعهدات في أداة مساعدة وحدة التحكم ومراقبة النتيجة باستخدام الالتزام . نتيجة لذلك ، تغيرت الإلتزامات وتبدو كما يلي:

 refactor(tutorial):      feat(products):      fix(products):

أصبحت قراءة القصة والتعرف على التغييرات أسهل. لم نرفض تحديد أرقام المهام ؛ فقد تم نقل كل شيء بدقة إلى ارتكاب وفقًا لاتفاقية الالتزامات التقليدية .

بعد ذلك ، سأريك كيفية تحقيق ترتيب مماثل في Git.

أفضل الممارسات والتوصيات والحلول الشائعة للتسميات

إذا حاولت فهم الممارسات المستخدمة في الصناعة ، يمكنك العثور على الخيارات التالية:

مقالات مع نصائح عامة لكتابة الأوامر. بالنسبة للجزء الأكبر ، فهي منطقية للغاية وتفتح موضوعًا جيدًا ، ولكن هناك شعور بالاضطراب وعدم وجود حل شامل لهذه المشكلة.
معايير الكتابة. هناك القليل منهم. إنها مستندات تحتوي على قائمة واضحة من القواعد ، وغالبًا ما تكتب خصيصًا لمكتبة كبيرة أو إطار عمل كبير. هذه المعايير تثير الإعجاب بنهج منتظم وشعبية ودعم في مجتمع المصادر المفتوحة.

نحن بحاجة إلى مزيد من النظام في ارتكاب!

تبرز منهجية الالتزامات التقليدية عن غيرها من المعايير وتستحق الدراسة عن كثب لعدة أسباب:

موثقة جيدا ومصممة. توفر مواصفاته إجابات على الأسئلة الأكثر شيوعًا.
استُلهم مُنشئو الاتفاقية من متطلبات أوامر الكتابة ، والتي تُستخدم في إطار AngularJS المشهور والذي تم اختباره مع الوقت.
تتبع قواعد الاتفاقية العديد من المكتبات الكبيرة مفتوحة المصدر (مثل yargs و lerna ).
إلى الإيجابيات ، سأستعد للتكوين التلقائي لملاحظات الإصدار وتغيير السجل.

مثال على الالتزام بهذا المعيار:

 fix(products):             -     .  : SECRETMRKT-578, SECRETMRKT-602

النقاط الرئيسية للالتزامات التقليدية

يجب أن يلتزم المطور بهيكل الالتزام التالي:
<النوع> (<النطاق>): <الموضوع>

<body>

<footer>
يجب أن يكون الالتزام رأسًا ، وربما جسمًا وتذييلًا.
يجب أن يبدأ رأس الالتزام بنوع يشير إلى تفاصيل التغييرات التي تم إجراؤها على قاعدة الشفرة ، وينتهي بوصف.
جنبا إلى جنب مع العمل الفذ الإلزامي ، وإصلاح (الذي ينظم استخدام صارم) ، ويسمح أنواع أخرى.
يمكن أن يكون للالتزام نطاق . إنه يميز قطعة من التعليمات البرمجية التي تأثرت بالتغييرات. تتبع المنطقة نوع الالتزام. لا ينظم المعيار قائمة واضحة بالمناطق. أمثلة على المناطق: eslint ، git ، التحليلات ، إلخ.
يجب أن يكون وصف الالتزام مباشرة بعد النوع / المنطقة.
يمكن استخدام جسم الالتزام للانتقال إلى التغييرات. يجب فصل الجسم عن الوصف بخط فارغ.
يجب استخدام تذييل الصفحة لتحديد الروابط الخارجية أو سياق الالتزام أو معلومات التعريف الأخرى. يجب فصل التذييل عن الجسم بخط فارغ.

بالإضافة إلى القواعد المدرجة في الاتفاقية ، نستخدم التوصيات الشائعة التالية:

في نص الالتزام نكتب ما تم تغييره ولماذا .

نستخدم الأنواع التالية من الإلتزامات:

بناء	بناء مشروع أو تغيير التبعيات الخارجية
ci	CI التكوين والبرمجة
مستندات	تحديث الوثائق
الفذ	إضافة وظائف جديدة
إصلاح	إصلاح الخلل
perf	تغييرات تحسين الأداء
ريفاكتور	تحرير التعليمات البرمجية دون إصلاح الأخطاء أو إضافة ميزات جديدة
العودة	التراجع إلى الإلتزامات السابقة
الاسلوب	تعديلات نمط الكود (علامات التبويب ، المسافات البادئة ، النقاط ، الفواصل ، إلخ)
اختبار	مضيفا الاختبارات

نكتب الوصف في مزاج حتمي ، تماما مثل جيت نفسها.
دمج فرع 'fix / SECRETMRKT-749-fix-typos-in-titles'
لا تحمّل وصف الالتزام بعلامات الترقيم.

الالتزامات التقليدية القياسية المستخدمة من قبل المساهمين ليرنا

كيفية التبديل ببساطة إلى الاسم الصحيح للالتزامات؟

تحتاج إلى إضافة الأتمتة والراحة. لحل هذه المشكلة ، نحتاج إلى أداتين: مولد الالتزام وفضلات الالتزام ، التي تم تكوينها للتحقق قبل الدفع إلى المستودع.

إعداد الأداة المساعدة المواطن

تتيح لك هذه الأداة إنشاء تعهدات باستخدام المعالج المضمن. بالإضافة إلى ذلك ، يتم دعم المواطن بشكل جيد من قبل المجتمع ، وبفضل الوحدات الإضافية ، يمكن تخصيصه بشكل كبير.

قم بتثبيت الأداة المساعدة العامة على مستوى العالم (قد تحتاج إلى حقوق المسؤول).
```
 npm i -g commitizen 
```
بعد ذلك ، قم بتثبيت المحول القابل للتخصيص . هناك حاجة لتكوين القالب مع الأسئلة المستخدمة من قبل الأداة المساعدة المواطن .
```
 npm i -D cz-customizable 
```

لنقم بإنشاء ملف commitizen.js ، يلزم تكوين cz-customizable. ضع الملف الذي تم إنشاؤه في الدليل ./config/git. أوصي بعدم تناثر جذر المشروع مع ملفات التكوين ومحاولة تجميع الملفات في مجلد تم إعداده لهذا الغرض. المحتوى:

عرض commitizen.js

 "use strict"; module.exports = { //         types: [ { value: "build", name: "build:      " }, { value: "ci", name: "ci:  CI    " }, { value: "docs", name: "docs:  " }, { value: "feat", name: "feat:   " }, { value: "fix", name: "fix:  " }, { value: "perf", name: "perf:     " }, { value: "refactor", name: "refactor:         " }, { value: "revert", name: "revert:    " }, { value: "style", name: "style:    (, , ,   ..)" }, { value: "test", name: "test:  " } ], // .    ,    scopes: [ { name: "components" }, { name: "tutorial" }, { name: "catalog" }, { name: "product" } ], //         (  'fix') /* scopeOverrides: { fix: [ {name: 'style'}, {name: 'e2eTest'}, {name: 'unitTest'} ] }, */ //    messages: { type: "   ?", scope: "\n ,    ():", //   allowCustomScopes  true customScope: "  :", subject: "     :\n", body: '   ().  "|"   :\n', breaking: " BREAKING CHANGES ():\n", footer: "    (,   ). : SECRETMRKT-700, SECRETMRKT-800:\n", confirmCommit: "   ?" }, //    allowCustomScopes: true, //   Breaking Changes allowBreakingChanges: false, //     footerPrefix: " :", // limit subject length subjectLimit: 72 };

أضف روابط إلى cz-للتخصيص وملف التكوين الذي تم إنشاؤه مسبقًا في package.json:
عرض جزء من package.json
```
 { "config": { "commitizen": { "path": "node_modules/cz-customizable" }, "cz-customizable": { "config": "config/git/commitizen.js" } }, } 
```
دعونا التحقق من النتيجة. اكتب الأمر التالي في الجهاز:
```
 git cz 
```

سيقوم المعالج التابع أولاً بجمع معلومات حول نوع ، ومنطقة الالتزام ، ثم يطلب بالتسلسل النص الذي سيكون في الوصف ، في النص ، في تذييل الصفحة ، وبعد موافقتك ، سينشئ التزامًا.

تأكد من إلقاء نظرة على مثال الأداة المساعدة المكونة والمحول cz-cusomizable المتصل به

قم بإعداد الأدوات المساعدة من أجش و الالتزام

تثبيت أجش و الالتزام في المشروع:
```
 npm i -D husky @commitlint/cli 
```
مع أجش ، سنضيف التحقق من الالتزام. للقيام بذلك ، في package.json ، مباشرة بعد البرامج النصية ، أضف الخطاف التالي وأشير فيه إلى رابط إلى ملف conflint.js:
عرض جزء من package.json
```
 { "scripts": { "test": "echo \"Error: no test specified\" && exit 1" }, "husky": { "hooks": { "commit-msg": "commitlint -E HUSKY_GIT_PARAMS -g './config/git/commitlint.js'" } }, "devDependencies": { "@commitlint/cli": "^7.2.1", "husky": "^1.1.3", } 
```

قم بإنشاء ملف conflint.js اللازم لكي يعمل linter بشكل صحيح. ضع الملف الذي تم إنشاؤه في الدليل ./config/git. محتويات الملف:

إظهار الالتزام

 //     @commitlint/config-conventional module.exports = { rules: { //        "body-leading-blank": [2, "always"], //         "footer-leading-blank": [2, "always"], //    72  "header-max-length": [2, "always", 72], //       "scope-case": [2, "always", "lower-case"], //      "subject-empty": [2, "never"], //     '.' "subject-full-stop": [2, "never", "."], //       "type-case": [2, "always", "lower-case"], //      "type-empty": [2, "never"], //      "type-enum": [ 2, "always", [ "build", "ci", "docs", "feat", "fix", "perf", "refactor", "revert", "style", "test" ] ] } };

هذا كل شيء. سيتم فحص جميع الالتزامات قبل إرسالها إلى المستودع :)

تأكد من إلقاء نظرة على مثال الأداة المساعدة للالتزام المكونة

فماذا تختار المواطن أو الالتزام؟

كل ذلك ، وآخر! بالتزامن ، فإنها تحقق نتائج ممتازة: الأول يولد يرتكب ، والثاني يتحقق لهم.

لماذا تنصح المعايير باستخدام الضرورة؟

هذا سؤال مهم للغاية. الالتزام هو تغيير الرمز ؛ يمكن اعتبار الرسالة في الالتزام إرشادات لتغيير هذا الرمز. إنشاء أو تغيير أو إضافة أو تحديث أو إصلاح - هذه كلها إرشادات محددة للمطور.

بالمناسبة ، يوصى بالحتمية في نظام إصدار Git نفسه :

 [[imperative-mood]] Describe your changes in imperative mood, eg "make xyzzy do frotz" instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy to do frotz", as if you are giving orders to the codebase to change its behavior.

لماذا التمسك أي اتفاقيات؟ هل يستحق الوقت؟ ما هو الربح؟

يستحق كل هذا العناء. بشكل عام ، لاحظت أننا أصبحنا أكثر استعدادًا لتوضيح التغييرات التي تم إجراؤها على قاعدة الشفرة. في نص الالتزام ، نصف بالتفصيل سبب وجوب استخدام هذه الحلول أو تلك الحلول. أصبح فهم التاريخ أسهل بموضوعية. بالإضافة إلى ذلك ، يتم تطوير منتجنا ، ونتوقع تجديده في الفريق. أنا متأكد من أنه بفضل إدخال المعيار والتشغيل الآلي ، سيكون من السهل على المبتدئين الاندماج في عملية التطوير.

حاول وشارك النتيجة.

روابط مفيدة:

مستودع مع كل رمز من هذه المادة.
ارتكاب التقليدية
Commitlint هي أداة للتحقق من صحة الالتزامات.
مكون على الانترنت من يرتكب الصحيح.
نصائح جيدة على ارتكاب التسمية.

كيفية توليد ارتكاب مغزى. تطبيق معيار الالتزامات التقليدية