Being clearer about use of RFC 2119

Đang mở
#796 9 bình luận 1 reaction 0 người được giao Xem trên GitHub

Chưa có ai nhận issue này.

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
28/100
Loại issue
Tài liệu
Độ rõ ràng
Cần làm rõ
Mức độ hoạt động
Đình trệ
Lĩnh vực
documentation

Hướng nghiên cứu

Bắt đầu với purpose_and_scope.html và RFC 2119, sau đó xem xét cách tiêu chuẩn sử dụng các thuật ngữ mang tính quy phạm như “should”, “must”, “may” và “optional”. Xác định những chỗ mà cách diễn đạt hoặc cách trình bày gây ra sự mơ hồ, và xác định việc hoàn thành là đạt được một giải thích RFC 2119 đã được thống nhất cùng với thuật ngữ hoặc định dạng nhất quán trong toàn bộ tiêu chuẩn.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

Narrative Content

We use RFC 2119 for words like "should" and "must" in the standard. But many people are confused by this and think that "should" restrictions are actually "must" restrictions. This is most common for dtype restrictions, but it appears in other places in the standard as well.

We need to be clearer about this somehow. Some suggestions

  • Capitalize (as is the common convention) or bold these words (https://github.com/data-apis/array-api/issues/397)

  • Add a section somewhere making it clear that we are following the RFC. There is a link to the RFC at the bottom of https://data-apis.org/array-api/latest/purpose_and_scope.html but that's it. The RFC itself says:

    Authors who follow these guidelines
    should incorporate this phrase near the beginning of their document:

    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
    NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
    "OPTIONAL" in this document are to be interpreted as described in
    RFC 2119.

  • The RFC also lists "required", "shall", "recommended", "may", and "optional". We should review our use of those terms to make sure they match the RFC.

  • We might be using "should" in places where we should be using "may" or "optional". From the RFC: SHOULD "means that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course", but MAY "means that an item is truly optional". Things like data type restrictions are probably correct in using SHOULD, but things like indexing restrictions, like out-of-bounds slices" perhaps ought to use MAY, since the only reason they are limited is so the the standard can support libraries that can't implement them.

  • We should consider if there are other ways things could be made clearer, for instance, explicitly stating "other behavior is unspecified".

Ngôn ngữ chính
Python
Star
281
Fork
52
Chỉ số merge pull request
Không có pull request nào được merge trong 30 ngày

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của data-apis/array-api

Tất cả issue của data-apis/array-api

Issue tương tự

Thêm issue về Python

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.