Automation between OTel repos #5817
Replies: 3 comments
-
Is this strictly for collector components and how we keep their docs in sync with the website or is this a larger request, since you made the following comment in the linked issue:
If it is around collector components, this is from my point of view a registry problem, and I tried to address some of that in this proposal: Registry Data Quality Improvements. I am more than happy to enable this, but we (SIG Comms) do not have the capacity to do that, that's why I put out that proposal: if there is a group of people that want to tackle the registry problem and run with it, I would be delighted, until then it's a gradual progress. If it is around a general request to be able to sync docs from a SIG's repo to the website repo, I would also be more than happy to reenable that, but there are once again a set of road blockers that require effort that is way beyond the capacity that our SIG has. I write "reenable", because there is some history to that. Also, we have some automation between repos already, for syncing versions, specs, some community pages.
After dumping that pile of problems on you, let me repeat the following: I would love to see this implemented that way, as it would push back the primary ownership of the docs to the SIGs where it (imho) belongs. |
Beta Was this translation helpful? Give feedback.
-
I think this is the main issue. Maybe we could start in a slower pace. Something like, whenever file Regarding the Registry, I'm not sure. I don't think it actually fits the Registry. Personally, I'd love to see something like this in the docs:
That's A LOT of work, and I don't think it should be responsibility of the SIG Comms to keep it all up-to-date. |
Beta Was this translation helpful? Give feedback.
-
The "do not assign" policy is especially relevant for people that show up and want to have an issue assigned to them and then never do something, or just use it as reference that they "contribute to OSS". That's why it is limited to people who didn't contribute to otel yet, which is not the case anymore for someone who has touched a file in the demo repo. So to make it short: if the Demo SIG wants to have an automation for that, I have no issue with that (@open-telemetry/docs-maintainers wdyt?). My requirement would be that it is then assigned to someone and labelled properly (sig:demo, etc.), so we do not have to do extra traige
I want to have it in the registry, because we can build pages from there for the components in a data-driven way best (e.g. via Content Adapters). I actually tried this once locally and it "works" to build a hierarchy as you described it, but this will create HUNDREDS of pages, which will massively slow down the build process and also since hugo is a static page generator if someone goes to docs.opentelemetry.io that navigation structure will be preloaded. So there is some work that needs to be done to make this possible.
ACK |
Beta Was this translation helpful? Give feedback.
-
Desired feature or idea: What would you like to see happen?
As the Collector moves to stable, the maintainers of it are defining requirements to move a component to different stability levels.
As of today, most of the components docs are under each component in a README or example file.
While discussing with @mx-psi in this issue, I've mentioned that it would be great to have documentation under the official OTel docs: opentelemetry.io.
The problem is that this would create an extra burden for codeowners and maintainers to keep track of 2 repos and making sure they are always in sync.
The actual feature request
Ideally, codeowners would write down the docs in the Collector repo in some sort of markdown, or yaml, or whatever we define, and the OTel docs page would render whatever is in this file in an user friendly way (not all users like reading READMEs and files in the GH repository).
Beta Was this translation helpful? Give feedback.
All reactions