Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

Feature Request: Facilitate enumerating protobuf plugin options in schema registry

Đã đóng
  • Có gì không ổn?
#1,703 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

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
25/100
Loại issue
Tính năng
Độ 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 bằng cách xem xét nội dung trang đích của plugin và ví dụ buf.plugin.yaml được liên kết trong repository bufbuild/plugins. So sánh hai phạm vi được đề xuất —các liên kết đến tài liệu dành cho tác giả và các tùy chọn được liệt kê— rồi làm rõ phạm vi nào được dự định trước khi xác định metadata của plugin bị ảnh hưởng và một định nghĩa hoàn thành có thể kiểm chứng.

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

Mô tả

Feature Request: Make Plugin Registry Documentation more useful and easier to maintain

This could be one of two things, depending on how ambitious:

  1. For every protobuf plugin, provide a link to the docs for the projec that owns/authored the plugin
  2. For every protobuf plugin, provide a list of the options (like a man page sort of thing)

WAIT, WAIT, WAIT ... OR we define our own data modeling language to define how we document and describe ALL possible values for ALL POSSIBLE options that could be... no, no... nevermind. Let's just stick with those first two.

I think I got spoiled by some of the nice documentation that was available from some of the more curated protobuf plugins.

I think I then conflated that with the Buf Schema Registry, so it could tell me what all the options were for any particular version of a particular protoc plugin.

For example, protoc-gen-go when run with --help provides a link to the exhaustive, and somewhat helpful: https://protobuf.dev/reference/go/go-generated where it mentions that all these options exist:

--go_opt=paths=source_relative
--go_opt=module=example.com/validator
--go_opt=M${PROTO_FILE}=${GO_IMPORT_PATH}
--go_opt=default_api_level=API_HYBRID
--go_opt=apilevelMhello.proto=API_HYBRID

but when I go to: https://buf.build/protocolbuffers/go?version=v1.36.4 I don't even see that documentation link, let alone a copy of the documentation, or some sort of summary of possible options. I really thought I did remember seeing something along those lines in the past. Maybe for one of the other plugins? I asked in Slack and Josh Humphries gave me this suggestion:

It can provide all of this information, but none of it is automatic since plugins don't have any sort of "interrogation" mode, where we could run a plugin binary and ask it for its options.
When it does provide this information, it will be on the plugin landing page, like the link you provided. In the public BSR (for free and team plans), we (Buf) curates the set of plugins and maintains the information that shows up on that page. That is all in an open-source repo here: https://github.com/bufbuild/plugins
It is possible that some of those plugin READMEs did contain information about plugin options. IIRC, the description field in buf.plugin.yaml (example) can be Markdown. But I'm not sure if it really changed and, if so, when. It is possible you've worked with a private BSR (pro or enterprise plan) that had custom plugins with that sort of documentation?

I think the challenge with keeping such docs in these curated plugins is just that it can trivially get out of sync with the actual plugin implementation as new versions are released. Perhaps we should at least add a link/URL to docs for the project that owns/authored the plugin.
Consider filing an issue at that bufbuild/plugins repo about fleshing out the description, at least with a link to other plugin docs. Maybe that will start a useful discussion on the subject or reveal other reasons why we don't already have it.

Ngôn ngữ chính
Dockerfile
Star
73
Fork
25
Merge trung bình
4 giờ 11 phút
Pull request đã merge (30 ngày)
55

Chuẩn bị môi trường

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 bufbuild/plugins

Tất cả issue của bufbuild/plugins

Issue tương tự

Thêm issue về Documentation

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.