Being clearer about use of RFC 2119
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ả
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
Bắt đầu từ đâu
- Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
- 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.
- Fork repository và làm thay đổi trên một nhánh.
- Mở pull request có tham chiếu số hiệu của issue.
Issue khác của data-apis/array-api
-
Độ khó 1/5 1-3 giờ Mức phù hợp với người mới 88/100
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 70/100
-
Độ khó 5/5 Hơn một tuần Mức phù hợp với người mới 35/100
-
Maintenance
data-apis/array-api#1012 · 2 bình luận · 1 người được giao ·
-
Độ khó 5/5 Hơn một tuần Mức phù hợp với người mới 25/100
Tất cả issue của data-apis/array-api
Issue tương tự
-
bug
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 82/100
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 88/100
use-agent-os/agent-os#3314 ·
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 75/100
BasedHardware/omi#15662 · 1 bình luận ·
-
documentation help wanted
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 90/100
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 62/100
AiursoftWeb/AnduinOS-2#19 ·