چه در حال اضافه کردن یک تابع زیان باشید، چه در حال بهبود پوشش تست، یا نوشتن یک RFC برای یک تغییر عمده در طراحی، این بخش از راهنمای مشارکتکنندگان به شما در شروع کار کمک خواهد کرد. از تلاش و علاقه شما برای بهبود TensorFlow متشکریم.
قبل از اینکه شروع کنید
قبل از اینکه کد منبع را به یک پروژه TensorFlow ارائه دهید، لطفاً فایل CONTRIBUTING.md را در مخزن GitHub پروژه بررسی کنید. برای مثال، به فایل CONTRIBUTING.md در مخزن اصلی TensorFlow مراجعه کنید. همه مشارکتکنندگان کد ملزم به امضای توافقنامه مجوز مشارکتکننده (CLA) هستند.
برای جلوگیری از تکرار کار، لطفاً RFC های فعلی یا پیشنهادی را بررسی کنید و قبل از شروع کار روی یک ویژگی غیرپیش پا افتاده، با توسعه دهندگان در انجمن های TensorFlow ( developers@tensorflow.org ) تماس بگیرید. ما هنگام تصمیم گیری برای اضافه کردن قابلیت های جدید تا حدودی گزینشی عمل می کنیم و بهترین راه برای مشارکت و کمک به پروژه، کار بر روی مسائل شناخته شده است.
مشکلات مربوط به مشارکتکنندگان جدید
مشارکتکنندگان جدید باید هنگام جستجوی اولین مشارکت در پایگاه کد TensorFlow، به دنبال برچسبهای زیر باشند. ما اکیداً توصیه میکنیم که مشارکتکنندگان جدید ابتدا پروژههای «اولین شماره خوب» و «مشارکت مورد استقبال» را انجام دهند. این به مشارکتکننده کمک میکند تا با گردش کار مشارکت آشنا شود و توسعهدهندگان اصلی نیز با مشارکتکننده آشنا شوند.
اگر به استخدام تیمی برای کمک به حل یک مشکل بزرگ یا یک ویژگی جدید علاقهمند هستید، لطفاً به گروه developers@ ایمیل بزنید و لیست فعلی RFC های ما را بررسی کنید.
بررسی کد
ویژگیهای جدید، رفع اشکالات و هرگونه تغییر دیگر در کد، منوط به بررسی کد هستند.
بررسی کدهایی که به پروژه کمک کردهاند، زیرا درخواستهای pull بخش مهمی از توسعه TensorFlow است. ما همه را تشویق میکنیم که بررسی کدهای ارسالی توسط سایر توسعهدهندگان را آغاز کنند، به خصوص اگر آن ویژگی چیزی است که احتمالاً از آن استفاده خواهید کرد.
در اینجا چند سوال وجود دارد که باید در طول فرآیند بررسی کد در نظر داشته باشید:
- آیا ما این را در TensorFlow میخواهیم؟ آیا احتمال استفاده از آن وجود دارد؟ آیا شما به عنوان یک کاربر TensorFlow، این تغییر را دوست دارید و قصد استفاده از آن را دارید؟ آیا این تغییر در محدوده TensorFlow است؟ آیا هزینه نگهداری یک ویژگی جدید ارزش مزایای آن را خواهد داشت؟
- آیا کد با API تنسورفلو سازگار است؟ آیا توابع عمومی، کلاسها و پارامترها به خوبی نامگذاری شده و به طور شهودی طراحی شدهاند؟
آیا شامل مستندات است؟ آیا تمام توابع عمومی، کلاسها، پارامترها، انواع بازگشتی و ویژگیهای ذخیره شده مطابق با قراردادهای TensorFlow نامگذاری شده و به وضوح مستند شدهاند؟ آیا قابلیتهای جدید در مستندات TensorFlow شرح داده شده و در صورت امکان با مثال نشان داده شدهاند؟ آیا مستندات به درستی رندر میشوند؟
آیا کد برای انسان قابل خواندن است؟ آیا افزونگی کمی دارد؟ آیا نام متغیرها باید برای وضوح یا سازگاری بهبود یابد؟ آیا باید نظرات اضافه شود؟ آیا باید نظراتی که مفید یا اضافی هستند حذف شوند؟
آیا کد کارآمد است؟ آیا میتوان آن را به راحتی بازنویسی کرد تا کارآمدتر اجرا شود؟
آیا کد با نسخههای قبلی TensorFlow سازگار است؟
آیا کد جدید وابستگیهای جدیدی به کتابخانههای دیگر اضافه خواهد کرد؟
تست و بهبود پوشش تست
تست واحد با کیفیت بالا، سنگ بنای فرآیند توسعه TensorFlow است. برای این منظور، ما از تصاویر Docker استفاده میکنیم. توابع تست به طور مناسب نامگذاری شدهاند و مسئول بررسی اعتبار الگوریتمها و همچنین گزینههای مختلف کد هستند.
تمام ویژگیهای جدید و رفع اشکالات باید شامل پوشش تست کافی باشند. ما همچنین از مشارکت موارد تست جدید یا بهبود تستهای موجود استقبال میکنیم. اگر متوجه شدید که تستهای موجود ما کامل نیستند - حتی اگر در حال حاضر باعث ایجاد اشکالی نشده باشند - لطفاً یک مشکل و در صورت امکان، یک درخواست pull ثبت کنید.
برای جزئیات خاص رویههای آزمایش در هر پروژه TensorFlow، به فایلهای README.md و CONTRIBUTING.md در مخزن پروژه در GitHub مراجعه کنید.
از نگرانیهای خاص در آزمایش کافی :
- آیا هر تابع و کلاس عمومی آزمایش میشود؟
- آیا مجموعهای معقول از پارامترها ، مقادیر آنها، انواع مقادیر و ترکیبات آنها آزمایش شده است؟
- آیا آزمایشها صحت کد و انجام کاری که در مستندات آمده است را تأیید میکنند؟
- اگر تغییر، رفع اشکال است، آیا آزمون غیر رگرسیونی نیز در آن گنجانده شده است؟
- آیا تستها از مرحلهی ساختِ یکپارچهسازی مداوم عبور میکنند ؟
- آیا تستها تمام خطوط کد را پوشش میدهند؟ اگر نه، آیا استثنائات منطقی و واضح هستند؟
اگر مشکلی پیدا کردید، لطفاً به مشارکتکننده کمک کنید تا آن مشکلات را درک کرده و آنها را حل کند.
بهبود پیامهای خطا یا گزارشها
ما از مشارکتهایی که پیامهای خطا و گزارشگیری را بهبود میبخشند، استقبال میکنیم.
گردش کار مشارکت
مشارکت در کد - رفع اشکال، توسعه جدید، بهبود تست - همه از یک گردش کار متمرکز بر GitHub پیروی میکنند. برای شرکت در توسعه TensorFlow، یک حساب GitHub ایجاد کنید. سپس:
مخزنی را که قصد دارید روی آن کار کنید، فورک کنید. به صفحه مخزن پروژه بروید و از دکمه فورک استفاده کنید. این کار یک کپی از مخزن را تحت نام کاربری شما ایجاد میکند. (برای جزئیات بیشتر در مورد نحوه فورک کردن یک مخزن، به این راهنما مراجعه کنید.)
مخزن را روی سیستم محلی خود کپی کنید.
$ git clone git@github.com:your-user-name/project-name.gitیک شاخه جدید برای نگهداری کار خود ایجاد کنید.
$ git checkout -b new-branch-nameروی کد جدیدتان کار کنید. تستها را بنویسید و اجرا کنید.
تغییرات خود را اعمال کنید.
$ git add -A$ git commit -m "commit message here"تغییرات خود را به مخزن گیتهاب خود ارسال کنید.
$ git push origin branch-nameیک درخواست pull (PR) باز کنید. به مخزن اصلی پروژه در GitHub بروید. پیامی در مورد شاخه اخیراً push شده شما نمایش داده میشود که از شما میپرسد آیا مایل به باز کردن یک درخواست pull هستید یا خیر. دستورالعملها را دنبال کنید، مخازن مختلف را مقایسه کنید و PR را ارسال کنید. با این کار ایمیلی برای اعمالکنندگان تغییرات ارسال میشود. میتوانید برای مشاهده بیشتر، ارسال ایمیل به لیست پستی را در نظر بگیرید. (برای جزئیات بیشتر، به راهنمای GitHub در مورد PRها مراجعه کنید.)
مدیران و سایر مشارکتکنندگان، PR شما را بررسی خواهند کرد. لطفاً در گفتگو شرکت کنید و سعی کنید تغییرات درخواستی را اعمال کنید . پس از تأیید PR، کد ادغام خواهد شد.
قبل از کار روی مشارکت بعدی خود ، مطمئن شوید که مخزن محلی شما بهروز است.
ریموت کنترل بالادستی را تنظیم کنید. (شما فقط باید این کار را یک بار در هر پروژه انجام دهید، نه همیشه.)
$ git remote add upstream git@github.com:tensorflow/project-repo-nameبه شاخه اصلی محلی بروید.
$ git checkout masterتغییرات را از بالادست (upstream) دریافت کنید.
$ git pull upstream masterتغییرات را به حساب گیتهاب خود اعمال کنید. (اختیاری، اما یک تمرین خوب است.)
$ git push origin masterاگر کار جدیدی را شروع میکنید، یک شاخه جدید ایجاد کنید.
$ git checkout -b branch-name
منابع اضافی git و گیتهاب:
چک لیست مشارکتکنندگان
- دستورالعملهای مشارکت را مطالعه کنید.
- آییننامه رفتار را بخوانید.
- مطمئن شوید که توافقنامه مجوز مشارکتکننده (CLA) را امضا کردهاید.
- بررسی کنید که آیا تغییرات شما با دستورالعملها مطابقت دارد یا خیر.
- بررسی کنید که آیا تغییرات شما با سبک کدنویسی TensorFlow سازگار است یا خیر.
- تستهای واحد را اجرا کنید .