Đóng góp cho mã TensorFlow

Cho dù bạn đang thêm hàm mất mát, cải thiện độ phủ kiểm thử hay viết đề xuất thay đổi thiết kế (RFC), phần này của hướng dẫn dành cho người đóng góp sẽ giúp bạn bắt đầu. Cảm ơn bạn vì công sức và sự quan tâm của bạn trong việc cải thiện TensorFlow.

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

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

Để tránh trùng lặp công việc, vui lòng xem xét các RFC hiện tại hoặc được đề xuất và liên hệ với các nhà phát triển trên diễn đàn TensorFlow ( developers@tensorflow.org ) trước khi bắt đầu làm việc trên một tính năng phức tạp. Chúng tôi khá 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à giúp đỡ dự án là giải quyết các vấn đề đã biết.

Những 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 mã nguồn TensorFlow. Chúng tôi đặc biệt khuyến khích những người đóng góp mới nên bắt đầu với các dự án thuộc loại “vấn đề đầu tiên tốt” và “đóng góp được hoan nghênh”; điều này giúp người đóng góp làm quen với quy trình đóng góp, và giúp 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 phát triển một tính năng mới, vui lòng gửi email đến nhóm developers@ và xem xét danh sách các yêu cầu đề xuất (RFC) hiện có 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 mã nguồn đều phải được xem xét mã.

Việc xem xét mã nguồn được đóng góp cho dự án thông qua các yêu cầu kéo (pull request) 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ã nguồn do các nhà phát triển khác gửi đến, đặc biệt nếu đó là tính năng mà bạn có khả năng 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ã nguồn:

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

  • Liệu nó có bao gồm tài liệu hướng dẫn không? Tất cả các hàm công khai, lớp, tham số, kiểu trả về và thuộc tính được lưu trữ có được đặt tên theo quy ước của 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à minh họa bằng ví dụ, nếu có thể không? Tài liệu có hiển thị đúng cách không?

  • Mã nguồn có dễ đọc đối với con người không? Có ít sự trùng lặp không? Có nên cải thiện tên biến để rõ ràng hoặc nhất quán hơn không? Có nên thêm chú thích không? Có nên loại bỏ bất kỳ chú thích nào không hữu ích hoặc không cần thiết không?

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

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

  • Liệu mã nguồn mới có tạo thêm các phụ thuộc vào các thư viện khác không?

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

Kiểm thử đơn vị chất lượng cao là nền tảng của quy trình phát triển TensorFlow. Vì mục đích này, chúng tôi sử dụng các ảnh Docker. Các hàm kiểm thử đượ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à bản vá lỗi đều phải có độ phủ kiểm thử đầy đủ. Chúng tôi cũng hoan nghênh sự đóng góp các trường hợp kiểm thử mới hoặc cải tiến các bài kiểm thử hiện có. Nếu bạn phát hiện ra rằng các bài kiểm thử hiện tại của chúng tôi chưa hoàn chỉnh — ngay cả khi điều đó hiện không gây ra lỗi — vui lòng báo cáo sự cố và, nếu có thể, gửi yêu cầu kéo (pull request).

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

Một trong những mối quan ngại đặc biệt về việc kiểm tra đầy đủ là:

  • Liệu mọi hàm và lớp công khai đều đã được kiểm thử chưa?
  • Liệu một tập hợp các tham số hợp lý , giá trị của chúng, kiểu giá trị và các tổ hợp tham số đã được kiểm tra chưa?
  • Các bài kiểm tra có xác nhận rằng mã nguồn là chính xác và đang thực hiện đúng chức năng được nêu trong tài liệu hay không?
  • Nếu thay đổi là để sửa lỗi, liệu có bao gồm cả bài 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 đã bao phủ mọi dòng mã chưa? Nếu chưa, các ngoại lệ có hợp lý và rõ ràng không?

Nếu bạn phát hiện bất kỳ vấn đề nào, vui lòng xem xét việc giúp người đóng góp hiểu rõ các vấn đề đó và giải quyết chúng.

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

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

Quy trình đóng góp

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

  1. Sao chép kho lưu trữ mà bạn định làm việc. Truy cập trang kho lưu trữ dự án và sử dụng nút "Fork" . Thao tác 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 sao chép kho lưu trữ, hãy xem hướng dẫn này .)

  2. Sao chép kho lưu trữ xuống 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 để lưu trữ công việc của bạn.

    $ git checkout -b new-branch-name

  4. Hãy tập trung vào đoạn mã mới của bạn. Viết và chạy các bài kiểm tra.

  5. Hãy xác nhận các 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 lên kho lưu trữ GitHub.

    $ git push origin branch-name

  7. Mở một Pull Request (PR). Truy cập vào kho lưu trữ dự án gốc trên GitHub. Sẽ có một thông báo về nhánh bạn vừa đẩy lên, hỏi bạn có muốn mở một pull request hay không. Làm theo hướng dẫn, so sánh giữa các kho lưu trữ và gửi PR. Thao tác này sẽ gửi một email đến những người chịu trách nhiệm đóng góp mã. Bạn cũng có thể cân nhắc gửi email đến danh sách gửi thư để được nhiều người biết đến hơn. (Để biết thêm chi tiết, hãy xem hướng dẫn của GitHub về PR ).

  8. Những người quản lý và các cộng tác viên khác sẽ xem xét yêu cầu kéo (PR) của bạn . Vui lòng tham gia vào cuộc thảo luậ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 chấp thuận, mã sẽ được hợp nhất.

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

  1. Thiết lập máy chủ từ xa phía thượng nguồn. (Bạn chỉ cần thực hiện việc này một lần cho mỗi dự án, không cần thiết phải làm 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. Tải xuống các thay đổi từ nguồn gốc.

    $ git pull upstream master

  4. Hãy đẩy các thay đổi lên tài khoản GitHub của bạn. (Không bắt buộc, nhưng nên làm.)

    $ git push origin master

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

    $ git checkout -b branch-name

Các nguồn tài liệu bổ sung về git và GitHub:

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