spec 1.0 · chuẩn tắc

Quản trị

Quản trị là yếu tố phân biệt lớp ngữ cảnh với wiki. Mô hình của nó là một vòng tròn: bình đẳng về quyền đọc, không bình đẳng về quyền quyết.

Vòng tròn, theo nghĩa chuẩn tắc#

Ai cũng đọc. Mọi bên tham gia, cả người lẫn agent, có quyền truy cập một lớp ngữ cảnh MUST đọc được toàn bộ lớp đó. Một lớp ngữ cảnh có chặn quyền đọc theo vai trò ở bên trong nó thì không phải một lớp ngữ cảnh dùng chung; ở nơi những người khác nhau được đọc những phần khác nhau, thì phần nội dung đó thuộc về những lớp ngữ cảnh riêng (xem Ranh giới truy cập bên dưới và distribution.md).
Ai cũng đề xuất. Mọi bên tham gia, người hay agent, MAY đề xuất thay đổi cho lớp ngữ cảnh. Đề xuất do agent soạn là hạng nhất: một agent phát hiện ngữ cảnh thiếu hoặc sai trong lúc làm việc SHOULD đề xuất phần sửa ngay trong cùng bộ thay đổi đã làm lộ ra vấn đề. Một đề xuất SHOULD mang theo phần lý giải đủ để người xem xét hiểu chủ ý và tác động dự kiến của nó; phần lý giải đó là mức tối thiểu mà một người cần để phê duyệt. Leji 1.0 không định nghĩa một giao thức bằng chứng tổng quát nào (xem Phạm vi của 1.0).
Người phê duyệt. Mọi thay đổi đối với lớp ngữ cảnh MUST được một người phê duyệt trước khi trở thành chính thống. Việc phê duyệt đi trên chính cơ chế xem xét sẵn có của kho mã nguồn (pull request); Leji không đưa vào một quy trình riêng nào. Việc tham gia MAY diễn ra qua bất kỳ giao diện nào, nhưng việc phê duyệt chính thống MUST là một bản ghi xem xét kiểm toán được trong chính cơ chế đó: quy được trách nhiệm cho người phê duyệt và gắn với đúng bộ thay đổi đang được xem xét. Một sự phê duyệt chỉ được nói ra trong thảo luận bên ngoài, trong chat, trong trạng thái một ticket, hay trong bình luận tài liệu, thì không được tính cho tới khi nó trở thành một bản ghi như vậy; và việc chép nó lại vào một bình luận cũng không tính. Mở rộng cách người ta tham gia không bao giờ dịch chuyển nơi thẩm quyền được ghi lại.

Yêu cầu#

Quyền sở hữu, không phải quyền tác giả. Manifest MUST nêu tên một chủ sở hữu chính (owners.primary) và MAY nêu tên một chủ sở hữu kế tục (owners.continuity): một người khác, gánh cùng phần trách nhiệm đó khi người chính vắng mặt hoặc rời đi. Một lần áp dụng có hỗ trợ từ bên ngoài SHOULD nêu tên chủ sở hữu kế tục trước khi bên hỗ trợ rút đi; một lớp ngữ cảnh của người làm một mình MAY không có ai, và điều đó nói thẳng ra rằng nó không có phương án kế tục. Chủ sở hữu là những con người chịu trách nhiệm: agent đề xuất và xem xét nhưng không bao giờ sở hữu, và việc nêu lại tên người chính vào ô kế tục thì chẳng cung cấp phương án nào. Chủ sở hữu chịu trách nhiệm về sức khoẻ của lớp ngữ cảnh: rằng nó luôn cập nhật, rằng nội dung lỗi thời hay mâu thuẫn được tỉa đi, và rằng mọi mảng đều có người chăm. Chủ sở hữu không phải người biên tập. Nội dung được cả vòng tròn viết ra và giữ cho đúng ngay trong lúc làm việc; dồn việc đó vào một người giữ đền chính là nút thắt cổ chai mà mô hình này sinh ra để tránh.
Phạm vi xem xét. Thay đổi trong lớp ngữ cảnh SHOULD được xem xét bởi những người gần nội dung bị ảnh hưởng nhất, tức chủ mảng, chứ không dồn hết qua một người gác cổng duy nhất. Quyền sở hữu theo mảng chính là bản đồ sở hữu sẵn có của kho mã nguồn (một tệp CODEOWNERS, một quy ước của nhóm), không phải một trường mới trong manifest; Leji dùng lại nó đúng như cách nó dùng lại pull request cho việc phê duyệt. Chủ sở hữu chính chịu trách nhiệm bảo đảm mảng nào cũng có người. Việc xem xét hỏi nhiều hơn câu “cái này có đúng không?”: vì sao nội dung này thuộc về lớp ngữ cảnh, ai sẽ dựa vào nó, điều gì cho thấy nó đứng vững, và khi nào thì nên xem lại. Một thay đổi không trả lời được những câu đó thì là một đường link hay một ghi chú, chứ không phải ngữ cảnh chính thống. Câu hỏi xem xét thường trực cho mọi bộ thay đổi là thay đổi này có làm đổi ngữ cảnh không?; nếu có, thì phần chênh lệch ngữ cảnh thuộc về cùng bộ thay đổi ấy.
Đưa vào và loại bỏ. Đề xuất thì mở; đưa vào thì không. Nội dung chỉ thuộc về lớp ngữ cảnh nếu nó làm đổi cách công việc sau này được làm: nó đặt ra một ràng buộc, mã hoá một quyết định, định nghĩa một giao diện hay một ranh giới sở hữu, hoặc chặn một sai lầm lặp lại. Mọi thứ khác thì được liên kết tới, không hấp thụ vào. Lớp ngữ cảnh MUST có một con đường loại bỏ chủ đích ngang với con đường phê duyệt của nó: nội dung lỗi thời, bị thay thế và trùng lặp được tỉa đi ngay trong các bộ thay đổi được xem xét thông thường, và việc tỉa là một phần bổn phận của từng chủ mảng, không phải một dự án dọn dẹp riêng. Một lớp ngữ cảnh chỉ có phình ra là một lớp đang mục ruỗng trong khi vẫn qua được vòng xem xét. Hướng dẫn có tính bền vững SHOULD vượt qua cổng chứng minh qua hai lần (theo content-categories.md): một bản vá dùng một lần thì cứ merge, nhưng một chuẩn mực chỉ trở thành chính thống sau khi nó đứng vững qua ít nhất hai tác vụ thật. Hãy đúc kết cái đang đúng, chứ không phải cái đang mong.
Kỷ luật changelog. Từ mức tuân thủ indexed trở lên, mọi thay đổi đã phê duyệt của lớp ngữ cảnh MUST ghi thêm một mục changelog máy đọc được theo machine-readable-surface.md.
Độ tươi. Độ tươi là một cơ chế của chủ ý: các tài liệu chủ ý và agent profile SHOULD mang hạn xem xét lại (freshness.reviewAfter trong mục index và trong profile), còn một bản ghi thì không mang gì cả (ngày của nó chính là tính cập nhật của nó, theo content-categories.md; một hạn xem xét lại khai trên một bản ghi là một lỗi kiểm tra). Công cụ SHOULD báo cáo những nội dung chủ ý đã quá hạn, và MUST NOT âm thầm coi nội dung lỗi thời là còn hiệu lực. Một người đọc nạp ngữ cảnh cho một tác vụ MUST làm nổi lên, ngay trong đầu ra của tác vụ đó, mọi mục đã nạp mà hạn xem xét lại đã trôi qua, để sự lỗi thời hiện ra trước mắt người chứ không bị chôn đi. Việc bản ghi kế tiếp được chờ đợi trong một chuỗi vận hành có quá hạn hay không là một khái niệm khác (độ mới của dòng bản ghi); 1.0 gọi tên nó nhưng không định nghĩa cơ chế nào cho nó. Ngữ cảnh bắt buộc của một tác vụ là hợp của tập nạp vô điều kiện trong boot profile, requiredRead của agent profile đang hoạt động, và lát cắt mà thuật toán Định tuyến tác vụ chọn cho tác vụ đó (các quyết định còn hiệu lực đã định tuyến và các tài liệu chủ ý được quản trị đã định tuyến, cộng với mọi bản ghi mà đường dẫn của tác vụ chọn trực tiếp, theo machine-readable-surface.md). Khi hạn của một mục bắt buộc đã hết, người đọc MUST dừng lại hoặc hỏi chứ không đi tiếp trên mục đó; hành động dựa trên ngữ cảnh đã biết là quá hạn xem xét chính là kiểu hỏng do âm thầm dùng nội dung lỗi thời mà quy tắc này sinh ra để ngăn. Một mục lỗi thời nhưng không bắt buộc thì MAY được dùng, kèm ghi chú rằng nó đã lỗi thời. Ở mức tuân thủ governed, hạn tươi MUST được khai báo và được kiểm (theo danh sách kiểm mức tuân thủ, kiểm ở dạng chỉ báo cáo là chấp nhận được); chạy phép kiểm đó trong CI là RECOMMENDED. Độ tươi về mặt xem xét lại (nói trên) khác với tính cập nhật của bản checkout: tức bản sao mà người đọc đang cầm có khớp với kho mã nguồn chính thống hay không. Người đọc xác lập tính cập nhật của bản checkout từ hệ quản lý phiên bản (git); cây làm việc chỉ cập nhật tới đúng phiên bản đã checkout, và công cụ MUST NOT âm thầm coi một bản sao chưa xác minh là còn hiệu lực. Một người đọc tiếp cận lớp ngữ cảnh dưới dạng nội dung tệp thuần, không có cây làm việc git hay siêu dữ liệu phiên bản nào truy cập được (nội dung tệp được tải lên hay đồng bộ sang một giao diện khác, không kèm kho mã nguồn), MUST coi tính cập nhật của bản checkout là không rõ chứ không coi là còn hiệu lực.
Nội dung chính thống sống trong lớp ngữ cảnh. Tri thức chi phối cách công việc được làm MUST NOT chỉ tồn tại trong một tệp cấu hình của nhà cung cấp, một luồng chat, hay sổ tay riêng của một cá nhân. Nếu nó chi phối công việc, nó thuộc về lớp ngữ cảnh, dưới vòng xem xét.

Ranh giới truy cập#

Leji không định nghĩa cơ chế kiểm soát truy cập nào của riêng mình. Quyền truy cập một lớp ngữ cảnh do hệ quản lý phiên bản (git) và nền tảng nơi kho mã nguồn nằm chi phối: phân quyền của bên chủ quản kho mã nguồn, cùng hệ tệp hay ổ đĩa dùng chung để lộ cây làm việc. Lớp ngữ cảnh chính là đơn vị của quyền truy cập.

Một lớp ngữ cảnh MAY nằm trong một kho mã nguồn có kiểm soát truy cập. Leji không cấp, không kiểm và không cưỡng chế quyền truy cập đó; hệ quản lý phiên bản và bên chủ quản của nó mới làm việc ấy.
Một lớp ngữ cảnh tuân thủ MUST NOT đòi hỏi việc chặn quyền đọc theo vai trò ở bên trong chính nó. Câu “ai cũng đọc được” chỉ áp trong phạm vi nhóm đối tượng của một lớp ngữ cảnh: mọi người mà hệ quản lý phiên bản cho vào đều đọc được toàn bộ lớp ngữ cảnh đó.
Nội dung cần một nhóm đối tượng hẹp hơn (ngữ cảnh cho ban điều hành, cho tài chính, cho an ninh, hay cho ứng cứu sự cố) MUST nằm trong một lớp ngữ cảnh riêng, với kho mã nguồn, manifest, chủ sở hữu và cổng xem xét của riêng nó, được phân quyền bởi hệ quản lý phiên bản. Ngữ cảnh bị giới hạn là một lớp ngữ cảnh riêng, không bao giờ là một vùng bị giới hạn bên trong một lớp dùng chung.
Việc ghép một lớp bị giới hạn vào ngữ cảnh của một nhóm khác là trường hợp federation, kèm các quy tắc bổ sung cho mount bị giới hạn trong distribution.md.

Mô hình bảo trì (tham khảo)#

Lớp ngữ cảnh được bảo trì qua từng thay đổi, ngay trong dòng công việc đang diễn ra: một tác vụ làm lộ ra ngữ cảnh thiếu hoặc sai; phần sửa nằm trong cùng bộ thay đổi được xem xét; changelog ghi lại thay đổi đó. Không cần một sprint riêng để viết tài liệu. Ngữ cảnh sai tạo ra đầu ra sai mà ai đó sẽ nhận thấy ngay trong ngày; phản hồi đó, kết hợp với vòng xem xét và CI chạy các phép kiểm cơ chế, tạo thành toàn bộ hệ thống cưỡng chế.

Vòng phản hồi nhanh phát hiện nội dung sai rất sớm. Còn sự tích tụ âm thầm của nội dung tầm thường hoặc dư thừa được xử lý bằng ngưỡng đưa vào và con đường loại bỏ nói trên, do chính chủ sở hữu từng mảng áp dụng. Đây là công việc biên tập mà Leji chủ ý phân tán. Một biên tập viên duy nhất có vẻ là cách an toàn để giữ chất lượng, nhưng thực tế lại trở thành điểm chậm nhất của hệ thống: thay đổi phải xếp hàng chờ hoặc đi vòng, trong khi người đó có ít ngữ cảnh hơn chuyên gia của từng mảng. Khi ấy, lớp ngữ cảnh sẽ đình trệ hoặc rẽ nhánh. Mỗi chủ mảng tự tinh gọn và trông coi phần của mình mới giúp toàn bộ lớp ngữ cảnh vừa gọn vừa chính xác mà không tạo nút thắt. Chủ sở hữu chăm lo sức khoẻ của hệ thống; vòng tròn chăm lo nội dung.