چه در حال افزودن یک تابع ضرر، بهبود پوشش تست، یا نوشتن یک RFC برای یک تغییر طراحی اصلی باشید، این بخش از راهنمای مشارکت‌کننده به شما کمک می‌کند تا شروع کنید. از کار و علاقه شما به بهبود TensorFlow سپاسگزاریم.
قبل از اینکه شروع کنید
قبل از اینکه کد منبع را به پروژه TensorFlow کمک کنید، لطفاً فایل CONTRIBUTING.md را در مخزن GitHub پروژه مرور کنید. برای مثال، فایل CONTRIBUTING.md را در مخزن هسته TensorFlow ببینید. همه مشارکت کنندگان کد ملزم به امضای قرارداد مجوز مشارکت (CLA) هستند.
برای جلوگیری از تکرار کار، لطفاً RFCهای فعلی یا پیشنهادی را مرور کنید و قبل از شروع کار روی یک ویژگی غیر ضروری، با توسعه دهندگان در انجمن های TensorFlow ( developers@tensorflow.org ) تماس بگیرید. ما هنگام تصمیم گیری برای افزودن قابلیت های جدید تا حدودی انتخابی هستیم و بهترین راه برای مشارکت و کمک به پروژه، کار روی مسائل شناخته شده است.
مسائلی برای مشارکت کنندگان جدید
مشارکت‌کنندگان جدید هنگام جستجوی اولین مشارکت در پایه کد TensorFlow باید به دنبال برچسب‌های زیر باشند. ما قویاً توصیه می‌کنیم که مشارکت‌کنندگان جدید ابتدا به پروژه‌های «اولین مسئله خوب» و «مشارکت استقبال می‌کنند» بپردازند. این به مشارکت کننده کمک می کند تا با گردش کار مشارکت آشنا شود و توسعه دهندگان اصلی با مشارکت کننده آشنا شوند.
اگر علاقه مند به استخدام تیمی برای کمک به مقابله با یک مشکل در مقیاس بزرگ یا یک ویژگی جدید هستید، لطفاً به گروه developers@ ایمیل بزنید و لیست فعلی RFC های ما را بررسی کنید.
بررسی کد
ویژگی‌های جدید، رفع باگ‌ها و هر تغییر دیگری در پایه کد قابل بررسی هستند.
بررسی کدهای ارائه شده به پروژه به عنوان درخواست های کششی یک جزء حیاتی در توسعه TensorFlow است. ما هر کسی را تشویق می کنیم که کد ارسال شده توسط توسعه دهندگان دیگر را بررسی کند، به خصوص اگر این ویژگی چیزی است که احتمالاً از آن استفاده می کنید.
در اینجا چند سوال وجود دارد که باید در طول فرآیند بررسی کد به خاطر داشته باشید:
- آیا ما این را در TensorFlow می خواهیم؟ احتمال استفاده هست؟ آیا شما به عنوان یک کاربر TensorFlow این تغییر را دوست دارید و قصد استفاده از آن را دارید؟ آیا این تغییر در محدوده TensorFlow است؟ آیا هزینه حفظ یک ویژگی جدید ارزش مزایای آن را دارد؟
- آیا کد با API TensorFlow سازگار است؟ آیا توابع عمومی، کلاس ها و پارامترها به خوبی نامگذاری شده و به طور مستقیم طراحی شده اند؟
آیا شامل مستندات می شود؟ آیا همه توابع عمومی، کلاس‌ها، پارامترها، انواع بازگشتی‌ها و ویژگی‌های ذخیره شده بر اساس قراردادهای TensorFlow نامگذاری شده‌اند و به وضوح مستند شده‌اند؟ آیا عملکرد جدید در مستندات TensorFlow توضیح داده شده و در صورت امکان با مثال هایی نشان داده شده است؟ آیا اسناد به درستی ارائه می شود؟
آیا این کد برای انسان قابل خواندن است؟ آیا افزونگی کم است؟ آیا نام متغیرها باید برای وضوح یا سازگاری بهبود یابد؟ آیا نظرات باید اضافه شود؟ آیا هر نظری باید به عنوان غیرمفید یا اضافی حذف شود؟
آیا کد کارآمد است؟ آیا می توان آن را به راحتی بازنویسی کرد تا کارآمدتر اجرا شود؟
آیا کد به عقب با نسخه‌های قبلی TensorFlow سازگار است ؟
آیا کد جدید وابستگی های جدیدی به کتابخانه های دیگر اضافه می کند؟
تست و بهبود پوشش تست
تست واحد با کیفیت بالا سنگ بنای فرآیند توسعه TensorFlow است. برای این منظور از تصاویر داکر استفاده می کنیم. توابع تست به درستی نامگذاری شده اند و مسئول بررسی اعتبار الگوریتم ها و همچنین گزینه های مختلف کد هستند.
تمام ویژگی‌های جدید و رفع اشکال باید شامل پوشش آزمایشی کافی باشد. ما همچنین از مشارکت موارد آزمایشی جدید یا بهبود در آزمایش‌های موجود استقبال می‌کنیم. اگر متوجه شدید که آزمایش‌های موجود ما کامل نیست - حتی اگر در حال حاضر باعث ایجاد یک باگ نمی‌شود - لطفاً یک مشکل و در صورت امکان، یک درخواست کشش ارسال کنید.
برای جزئیات خاص مراحل آزمایش در هر پروژه TensorFlow، به فایل‌های README.md و CONTRIBUTING.md در مخزن پروژه در GitHub مراجعه کنید.
نگرانی های خاص در آزمایش کافی :
- آیا هر تابع عمومی و کلاس تست شده است؟
- آیا مجموعه معقولی از پارامترها ، مقادیر، انواع مقادیر و ترکیبات آنها آزمایش شده است؟
- آیا آزمایش‌ها تأیید می‌کنند که کد صحیح است ، و آن کاری را انجام می‌دهد که مستندات می‌گوید کد در نظر گرفته شده است؟
- اگر این تغییر یک رفع اشکال باشد، آیا تست بدون رگرسیون نیز گنجانده شده است؟
- آیا تست ها از ساخت ادغام پیوسته عبور می کنند ؟
- آیا تست ها هر خط کد را پوشش می دهند؟ اگر نه، آیا استثنائات معقول و صریح است؟
اگر مشکلی پیدا کردید، لطفاً به مشارکت کننده کمک کنید تا آن مشکلات را درک کند و آنها را حل کند.
پیام های خطا یا گزارش ها را بهبود بخشید
ما از مشارکت هایی که پیام های خطا و گزارش را بهبود می بخشد استقبال می کنیم.
گردش کار مشارکت
مشارکت های کد - رفع اشکال، توسعه جدید، بهبود تست - همگی از یک گردش کاری متمرکز بر GitHub پیروی می کنند. برای شرکت در توسعه TensorFlow، یک حساب GitHub راه اندازی کنید. سپس:
انباری را که می‌خواهید روی آن کار کنید فوکوس کنید. به صفحه مخزن پروژه بروید و از دکمه Fork استفاده کنید. با این کار یک کپی از مخزن تحت نام کاربری شما ایجاد می شود. (برای جزئیات بیشتر در مورد نحوه چنگال کردن یک مخزن به این راهنما مراجعه کنید.)
مخزن را در سیستم محلی خود کلون کنید.
$ 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"تغییرات خود را به مخزن GitHub خود فشار دهید.
$ git push origin branch-nameدرخواست کشش (PR) را باز کنید. به مخزن اصلی پروژه در GitHub بروید. پیامی در مورد شعبه اخیراً هل داده شده شما ارسال می شود که از شما می پرسد آیا می خواهید یک درخواست کشش باز کنید. دستورات را دنبال کنید، بین مخازن مقایسه کنید و PR را ارسال کنید. این یک ایمیل برای committer ها ارسال می کند. ممکن است بخواهید برای مشاهده بیشتر یک ایمیل به لیست پستی ارسال کنید. (برای جزئیات بیشتر، راهنمای GitHub در PRs را ببینید.
نگهبانان و سایر مشارکت کنندگان روابط عمومی شما را بررسی خواهند کرد. لطفاً در گفتگو شرکت کنید و سعی کنید تغییرات درخواستی را انجام دهید . پس از تایید روابط عمومی، کد ادغام خواهد شد.
قبل از کار بر روی مشارکت بعدی خود ، مطمئن شوید که مخزن محلی شما به روز است.
کنترل از راه دور بالادست را تنظیم کنید. (شما فقط باید این کار را یک بار در هر پروژه انجام دهید، نه هر بار.)
$ git remote add upstream git@github.com:tensorflow/project-repo-nameبه شعبه اصلی محلی بروید.
$ git checkout masterتغییرات را از بالادست پایین بکشید.
$ git pull upstream masterتغییرات را به حساب GitHub خود فشار دهید. (اختیاری، اما تمرین خوبی است.)
$ git push origin masterاگر کار جدیدی را شروع می کنید، یک شعبه جدید ایجاد کنید.
$ git checkout -b branch-name
منابع git و GitHub اضافی:
چک لیست مشارکت کنندگان
- دستورالعمل های کمک کننده را بخوانید.
- قوانین رفتاری را بخوانید.
- اطمینان حاصل کنید که قرارداد مجوز مشارکت (CLA) را امضا کرده اید.
- بررسی کنید که آیا تغییرات شما با دستورالعمل ها مطابقت دارد یا خیر.
- بررسی کنید که آیا تغییرات شما با سبک کدنویسی TensorFlow مطابقت دارد یا خیر.
- تست های واحد را اجرا کنید .