Khả năng tương thích: một bản phát hành cam kết những gì
Việc nâng cấp Aggrega có thể thay đổi một số bề mặt mà bạn xây dựng dựa trên: các lược đồ mà tài liệu của bạn được viết theo, các lệnh và cờ mà script của bạn gọi, các công cụ mà trợ lý AI gọi, các mã lỗi mà bạn ghi lại, và các bộ công cụ plugin dùng để xây dựng plugin. Trang này nêu rõ, với từng bề mặt, những gì một bản phát hành có thể thay đổi và những gì không. Một bề mặt mà trang này không nêu tên không mang cam kết nào ngoài những gì trang tham chiếu riêng của nó nêu. Phần cuối cho biết nơi một bản phát hành thông báo cho bạn rằng một trong số chúng đã thay đổi. Các cam kết trên trang này bắt đầu từ phiên bản 0.9.0. Các Releases trước phiên bản 0.9.0 không được hỗ trợ: kho đăng ký hub, hub.aggrega.ai, không cung cấp phiên bản Plugin nào được tạo cho chúng, và trình biên dịch của chúng không thể đọc danh mục của kho đăng ký này, mà các tài liệu trong đó khai báo aggrega.ai/v1beta1.
Aggrega được phát hành dưới dạng các phiên bản 0.x.y: bản phát hành patch tăng số cuối cùng, bản phát hành minor tăng số ở giữa. metadata.version riêng của một thực thể danh mục là một vấn đề khác — tác giả của nó tự chọn, theo các tiêu chí tăng phiên bản mà aggrega lint --pre-publish kiểm tra, và Phân giải phiên bản mô tả cách một tham chiếu chọn một phiên bản.
Lược đồ
Mọi lược đồ mà Aggrega công bố đều thuộc về một phiên bản API, aggrega.ai/v1beta1 — giá trị mà một tài liệu thực thể khai báo trong apiVersion của nó. Quy tắc dưới đây áp dụng cho từng lược đồ: các loại thực thể, payload của plugin, cùng các lược đồ không gian làm việc và các lược đồ khác — IR, cấu hình không gian làm việc, các tệp khóa và phần còn lại — tất cả đều được liệt kê trong Tham chiếu lược đồ. Phiên bản API tách biệt với số hiệu bản phát hành: nhiều bản phát hành đọc cùng một phiên bản API.
Những gì có thể thay đổi trong v1beta1
Trong một phiên bản API, lược đồ chỉ thay đổi theo hướng bổ sung, giống như cách Kubernetes thay đổi các phiên bản API của chính nó. Một bản phát hành có thể:
- thay đổi một mô tả;
- thêm một trường, khi trường đó là tùy chọn.
Mọi tài liệu hợp lệ trước một thay đổi như vậy vẫn hợp lệ sau thay đổi đó và mang cùng ý nghĩa. Một chương trình đọc tài liệu do trình biên dịch ghi ra, chẳng hạn IR hoặc một tệp khóa, cần chấp nhận một trường mà nó không biết, vì một trường tùy chọn được thêm vào có thể xuất hiện trong đầu ra đó trong phạm vi v1beta1.
Những gì cần đến v1beta2
Mỗi thay đổi sau đây đều cần một phiên bản API mới, aggrega.ai/v1beta2:
- xóa hoặc đổi tên một trường;
- biến một trường thành bắt buộc;
- thu hẹp một kiểu, hoặc tập giá trị mà một trường chấp nhận;
- thay đổi ý nghĩa của một giá trị.
Một phiên bản API mới là một thay đổi phá vỡ tương thích, được lên lịch và thông báo như vậy trong bản phát hành mang nó đến.
Một trường tùy chọn mới đến với danh mục cùng trình biên dịch nhận biết nó
Trình biên dịch từ chối một trường mà lược đồ của nó không khai báo. Chính sự chặt chẽ đó giúp phát hiện một khóa viết sai chính tả, và nó có một hệ quả mà người đọc khó đoán được: một thực thể danh mục chỉ có thể bắt đầu dùng một trường tùy chọn mới được thêm vào trong một bản phát hành có kèm trình biên dịch nhận biết trường đó.
Ví dụ, giả sử một bản phát hành thêm một trường tùy chọn vào lược đồ Component — gọi nó là spec.newField:
- Mọi Component được viết trước bản phát hành đó vẫn hợp lệ; không cái nào đặt trường này.
- Một tác giả danh mục công bố một phiên bản mới của một Component có đặt
spec.newField. - Trình biên dịch từ bản phát hành đó, hoặc một bản phát hành sau đó, xác thực và xây dựng Component.
- Trình biên dịch từ một bản phát hành trước đó từ chối nó, vì lược đồ của chính nó không khai báo trường này: quá trình xác thực báo
spec.newField: unexpected propertyvà chỉ ra dòng.
Vì vậy, bất kỳ ai xây dựng dựa trên phiên bản danh mục đó sẽ nâng cấp trước lên bản phát hành đã thêm trường này, và một danh mục chỉ công bố thực thể dùng trường này khi bản phát hành đó đã ra mắt. Cách một Release đã khóa giữ lại các phiên bản mà nó đã phân giải được trình bày trong Phân giải phiên bản.
Dòng lệnh và các công cụ trợ lý
Script, pipeline CI và cấu hình trợ lý gọi các lệnh aggrega, cờ và công cụ trợ lý theo tên. Trong các bản phát hành 0.x:
- Một bản phát hành patch không bao giờ xóa hoặc đổi tên một lệnh, một cờ hay một công cụ trợ lý.
- Một bản phát hành minor có thể xóa hoặc đổi tên một trong số đó, và nhật ký thay đổi của nó ghi rõ điều này dưới Removed hoặc Changed.
- Các bổ sung — một lệnh, cờ hoặc công cụ mới — có thể xuất hiện trong bất kỳ bản phát hành nào.
Các công cụ trợ lý là các công cụ mà aggrega mcp cung cấp cho một trợ lý được kết nối. Danh sách đầy đủ của chúng chính là câu trả lời của máy chủ, và Trợ lý của bạn có thể làm gì với Aggrega cho biết cách yêu cầu danh sách đó. Một công cụ chạy một lệnh lấy tên từ đường dẫn gọi của lệnh đó, nên đổi tên một lệnh cũng đổi tên công cụ của nó. Tổng quan CLI liệt kê mọi lệnh.
Mã lỗi
Mọi điều kiện gây dừng đều mang một mã ngắn — chữ cái E và bốn chữ số, như trong [DEVELOPER_ERROR E0007] — được in ở đầu thông báo chẩn đoán của nó. Các mã ngắn là một hợp đồng công khai: một mã chỉ được cấp một lần, không bao giờ bị đánh số lại và không bao giờ được cấp cho một điều kiện khác. Mã của một điều kiện đã ngừng sử dụng vẫn giữ trạng thái ngừng sử dụng, nên một mã được ghi trong runbook, một quy tắc CI hoặc một issue luôn chỉ cùng một điều kiện sau mọi lần nâng cấp.
Sentinel lỗi giải thích các định danh mà một điều kiện mang — mã ngắn mà con người trích dẫn, mã mô tả mà chương trình ghi lại và accessor Go mà chương trình dùng để so khớp — mỗi định danh cam kết điều gì, và cách ngăn một số đã ngừng sử dụng bị cấp lại. Bảng mọi điều kiện của trang đó tra ra mọi mã ngắn, kể cả các mã đã ngừng sử dụng, và aggrega explain tra một mã ngay tại terminal.
Bộ công cụ Plugin
Các bộ công cụ phát triển plugin — github.com/aggrega-ai/aggrega-pdk/go, aggrega-pdk-rust và @aggrega-ai/aggrega-pdk-typescript — cùng các codec aggrega-abi mà chúng tái xuất tuân theo cách đánh phiên bản ngữ nghĩa kể từ 0.9.0. Ba ngôn ngữ của các bộ công cụ dùng chung một số phiên bản, và ba ngôn ngữ của các codec dùng chung một số phiên bản khác.
- Một plugin được xây dựng dựa trên một phiên bản vẫn tiếp tục xây dựng được dựa trên mọi bản phát hành sau đó của cùng dòng. Trong
0.9.x, một bản phát hành có thể thêm các hàm, kiểu và hằng số được xuất, và không bao giờ xóa hay thay đổi bất kỳ cái nào. - Một thay đổi phá vỡ tương thích đối với một API được xuất chỉ được phát hành trong một phiên bản minor mới (từ
0.9.xlên0.10.0), và một bản phát hành patch không bao giờ phá vỡ tương thích. Các bộ công cụ và codec chuyển lên1.0.0cùng lúc với1.0.0của chính Aggrega, sau đó một thay đổi phá vỡ tương thích sẽ tăng số major. - Một thay đổi phá vỡ tương thích trong các codec là một thay đổi phá vỡ tương thích trong các bộ công cụ, vốn sẽ tăng phiên bản minor của chính chúng theo, vì chúng tái xuất các kiểu codec.
- Việc một trường hoặc thành viên được thêm vào một kiểu hiện có có được tính là một bổ sung hay không phụ thuộc vào ngôn ngữ. README của mỗi bộ công cụ, được công bố cùng gói, nêu trường hợp của ngôn ngữ đó dưới mục “Compatibility”.
Cam kết này bao trùm API mà mã nguồn của một plugin gọi tên. Những gì đi qua giữa trình biên dịch và một plugin đang chạy thì do phiên bản ABI của plugin đảm bảo: trong một phiên bản ABI, một socket chỉ có thêm mô tả và trường tùy chọn, nên một plugin được xây dựng dựa trên phiên bản đó vẫn tiếp tục được tải. Hợp đồng plugin mô tả các socket, và hướng dẫn dành cho nhà phát triển plugin mô tả quy trình làm việc xoay quanh chúng.
Nhật ký thay đổi của một bản phát hành cho biết gì
Ghi chú của mỗi bản phát hành, trên trang các bản phát hành, chứa nhật ký thay đổi của nó, được nhóm dưới các tiêu đề như Added, Changed, Removed và Fixed. Đối với các bề mặt trên trang này:
- Một lệnh, cờ hoặc công cụ trợ lý bị xóa hoặc đổi tên được liệt kê dưới Removed hoặc Changed, trong bản phát hành minor thực hiện thay đổi đó.
- Một phiên bản API lược đồ mới được thông báo là thay đổi phá vỡ tương thích trong bản phát hành mang nó đến.
- Một thay đổi phá vỡ tương thích đối với các bộ công cụ plugin hoặc các codec thể hiện qua số phiên bản của chúng: đó là một phiên bản minor mới dưới
1.0.0. - Một mã lỗi không bao giờ đổi ý nghĩa, nên không có bản phát hành nào phải thông báo về điều đó.