Đóng góp cho mã TensorFlow

Cho dù bạn đang thêm một hàm mất mát, cải thiện phạm vi kiểm thử hay viết RFC cho một thay đổi lớn về thiết kế, phần hướng dẫn cộng tác viên này sẽ giúp bạn bắt đầu. Cảm ơn bạn đã nỗ lực và quan tâm đến việc cải thiện TensorFlow.

Trước khi bạn bắt đầu

Trước khi bạn đóng góp mã nguồn cho dự án TensorFlow, vui lòng xem lại tệp CONTRIBUTING.md trong kho GitHub của dự án. Ví dụ: xem tệp CONTRIBUTING.md trong kho lõi TensorFlow. Tất cả những người đóng góp mã được yêu cầu ký Thỏa thuận cấp phép cộng tác viên (CLA).

Để tránh trùng lặp công việc, vui lòng xem lại RFC hiện tại hoặc được đề xuất và liên hệ với nhà phát triển trên diễn đàn TensorFlow ( developers@tensorflow.org ) trước khi bạn bắt đầu làm việc trên một tính năng không tầm thường. Chúng tôi có phần chọn lọc khi quyết định thêm chức năng mới và cách tốt nhất để đóng góp và hỗ trợ dự án là giải quyết các vấn đề đã biết.

Các vấn đề dành cho người đóng góp mới

Những người đóng góp mới nên tìm kiếm các thẻ sau khi tìm kiếm đóng góp đầu tiên cho cơ sở mã TensorFlow. Chúng tôi đặc biệt khuyến nghị những người đóng góp mới nên giải quyết các dự án “vấn đề đầu tiên tốt” và “hoan nghênh đóng góp” trước; điều này giúp người đóng góp làm quen với quy trình đóng góp và để các nhà phát triển cốt lõi làm quen với người đóng góp.

Nếu bạn quan tâm đến việc tuyển dụng một nhóm để giúp giải quyết một vấn đề quy mô lớn hoặc một tính năng mới, vui lòng gửi email cho nhóm nhà phát triển@ và xem lại danh sách RFC hiện tại của chúng tôi.

Đánh giá mã

Các tính năng mới, sửa lỗi và bất kỳ thay đổi nào khác đối với cơ sở mã đều phải được xem xét mã.

Việc xem xét mã đóng góp cho dự án dưới dạng yêu cầu kéo là một thành phần quan trọng trong quá trình phát triển TensorFlow. Chúng tôi khuyến khích mọi người bắt đầu xem xét mã do các nhà phát triển khác gửi, đặc biệt nếu tính năng này là thứ mà bạn có thể sẽ sử dụng.

Dưới đây là một số câu hỏi cần lưu ý trong quá trình xem xét mã:

  • Chúng ta có muốn điều này trong TensorFlow không? Nó có khả năng được sử dụng không? Bạn, với tư cách là người dùng TensorFlow, có thích sự thay đổi này và có ý định sử dụng nó không? Đây có phải là sự thay đổi trong phạm vi của TensorFlow không? Chi phí duy trì một tính năng mới có xứng đáng với lợi ích của nó không?
  • Mã có nhất quán với API TensorFlow không? Các hàm, lớp và tham số công khai có được đặt tên rõ ràng và được thiết kế trực quan không?

  • Nó có bao gồm tài liệu không? Tất cả các hàm, lớp, tham số, kiểu trả về và thuộc tính được lưu trữ công khai có được đặt tên theo quy ước TensorFlow và được ghi chép rõ ràng không? Chức năng mới có được mô tả trong tài liệu của TensorFlow và được minh họa bằng ví dụ bất cứ khi nào có thể không? Tài liệu có hiển thị đúng không?

  • Mã có thể đọc được bằng con người không? Mức độ dư thừa có thấp không? Tên biến có nên được cải thiện cho rõ ràng và nhất quán không? Có nên thêm ý kiến? Có nên xóa bất kỳ nhận xét nào vì không hữu ích hoặc không liên quan không?

  • Mã có hiệu quả không? Nó có thể được viết lại dễ dàng để chạy hiệu quả hơn không?

  • Mã này có tương thích ngược với các phiên bản trước của TensorFlow không?

  • Mã mới có thêm phần phụ thuộc mới vào các thư viện khác không?

Kiểm tra và cải thiện phạm vi kiểm tra

Thử nghiệm đơn vị chất lượng cao là nền tảng của quá trình phát triển TensorFlow. Với mục đích này, chúng tôi sử dụng hình ảnh Docker. Các hàm kiểm tra được đặt tên phù hợp và chịu trách nhiệm kiểm tra tính hợp lệ của các thuật toán cũng như các tùy chọn khác nhau của mã.

Tất cả các tính năng mới và sửa lỗi phải bao gồm phạm vi kiểm tra đầy đủ. Chúng tôi cũng hoan nghênh sự đóng góp của các trường hợp thử nghiệm mới hoặc cải tiến cho các thử nghiệm hiện có. Nếu bạn phát hiện ra rằng các thử nghiệm hiện tại của chúng tôi chưa hoàn tất — ngay cả khi điều đó hiện không gây ra lỗi — vui lòng gửi vấn đề và nếu có thể, gửi yêu cầu kéo.

Để biết chi tiết cụ thể về quy trình thử nghiệm trong từng dự án TensorFlow, hãy xem tệp README.md và CONTRIBUTING.md trong kho lưu trữ dự án trên GitHub.

Các mối quan tâm đặc biệt trong việc kiểm tra đầy đủ :

  • Mọi chức năng và lớp công khai có được kiểm tra không?
  • Tập hợp các tham số, giá trị, loại giá trị và sự kết hợp hợp lý của chúng có được kiểm tra không?
  • Các cuộc kiểm tra có xác nhận rằng mã đó đúng và nó đang thực hiện những gì tài liệu cho biết mã dự định thực hiện không?
  • Nếu thay đổi là sửa lỗi thì có bao gồm kiểm tra không hồi quy không?
  • Các bài kiểm tra có vượt qua quá trình xây dựng tích hợp liên tục không?
  • Các bài kiểm tra có bao gồm mọi dòng mã không? Nếu không, các trường hợp ngoại lệ có hợp lý và rõ ràng không?

Nếu bạn tìm thấy bất kỳ vấn đề nào, vui lòng cân nhắc việc giúp người đóng góp hiểu những vấn đề đó và giải quyết chúng.

Cải thiện thông báo lỗi hoặc nhật ký

Chúng tôi hoan nghênh những đóng góp giúp cải thiện thông báo lỗi và ghi nhật ký.

Quy trình đóng góp

Đóng góp mã—sửa lỗi, phát triển mới, cải tiến thử nghiệm—tất cả đều tuân theo quy trình làm việc lấy GitHub làm trung tâm. Để tham gia phát triển TensorFlow, hãy thiết lập tài khoản GitHub. Sau đó:

  1. Fork repo mà bạn dự định làm việc. Chuyển đến trang repo dự án và sử dụng nút Fork . Điều này sẽ tạo một bản sao của kho lưu trữ dưới tên người dùng của bạn. (Để biết thêm chi tiết về cách phân nhánh kho lưu trữ, hãy xem hướng dẫn này .)

  2. Sao chép repo vào hệ thống cục bộ của bạn.

    $ git clone git@github.com:your-user-name/project-name.git

  3. Tạo một nhánh mới để thực hiện công việc của bạn.

    $ git checkout -b new-branch-name

  4. Làm việc trên mã mới của bạn. Viết và chạy thử nghiệm.

  5. Cam kết thay đổi của bạn.

    $ git add -A

    $ git commit -m "commit message here"

  6. Đẩy các thay đổi của bạn vào kho lưu trữ GitHub của bạn.

    $ git push origin branch-name

  7. Mở Yêu cầu Kéo (PR). Chuyển đến kho lưu trữ dự án ban đầu trên GitHub. Sẽ có một thông báo về nhánh được đẩy gần đây của bạn, hỏi bạn có muốn mở yêu cầu kéo không. Làm theo lời nhắc, so sánh giữa các kho lưu trữ và gửi PR. Điều này sẽ gửi một email đến những người cam kết. Bạn có thể muốn xem xét việc gửi email đến danh sách gửi thư để dễ thấy hơn. (Để biết thêm chi tiết, hãy xem hướng dẫn GitHub về PR .

  8. Người bảo trì và những người đóng góp khác sẽ xem xét PR của bạn . Vui lòng tham gia vào cuộc trò chuyện và cố gắng thực hiện bất kỳ thay đổi nào được yêu cầu . Sau khi PR được phê duyệt, mã sẽ được hợp nhất.

Trước khi thực hiện đóng góp tiếp theo của bạn , hãy đảm bảo kho lưu trữ cục bộ của bạn được cập nhật.

  1. Đặt điều khiển từ xa ngược dòng. (Bạn chỉ phải thực hiện việc này một lần cho mỗi dự án, không phải mọi lần.)

    $ git remote add upstream git@github.com:tensorflow/project-repo-name

  2. Chuyển sang nhánh chính cục bộ.

    $ git checkout master

  3. Kéo xuống những thay đổi từ thượng nguồn.

    $ git pull upstream master

  4. Đẩy các thay đổi vào tài khoản GitHub của bạn. (Tùy chọn, nhưng đây là một cách thực hành tốt.)

    $ git push origin master

  5. Tạo một chi nhánh mới nếu bạn đang bắt đầu công việc mới.

    $ git checkout -b branch-name

Tài nguyên git và GitHub bổ sung:

Danh sách kiểm tra dành cho người đóng góp