Summary
I'd like to propose improving the documentation for contributing Blueprints and Reference Implementations to make the existing contribution workflow clearer and easier to follow for new contributors.
While the current documentation explains how to submit a proposal, it doesn't describe the complete journey from proposal to merged documentation in a single place.
Motivation
The current documentation explains how to create a proposal issue, but it doesn't clearly describe what happens afterwards.
For example, a contributor could reasonably assume they should immediately open a pull request against the opentelemetry.io repository after creating a proposal issue. In practice, contributors are expected to wait until their proposal has been reviewed and approved by the Blueprints Team before opening a documentation PR.
Making this workflow explicit would help set clear expectations and reduce unnecessary work for both contributors and reviewers.
Proposed improvements
End User SIG repository
Add dedicated documentation describing the contribution workflow, for example:
- architecture/blueprint-contribution-process.md
- architecture/reference-implementation-contribution-process.md
These documents could describe:
- prerequisites for contributors,
- proposal workflow,
- review and approval process,
- when to open a documentation pull request,
- review expectations,
- required templates,
- links to relevant repositories and documentation
OpenTelemetry documentation (opentelemetry.io)
Update the contributor guidance to reference the new contribution documentation by:
- adding links to architecture/blueprint-contribution-process.md and architecture/reference-implementation-contribution-process.md,
- updating the Blueprints and Reference Implementations page to clarify that contributors should first submit a proposal issue and only open a documentation pull request after the proposal has been reviewed and approved by the Blueprints Team.
Implementation
If there is agreement on this proposal, I'd be happy to implement these documentation improvements and submit the corresponding pull requests to both the sig-end-user and opentelemetry.io repositories.
Background
This topic was discussed during the most recent End User SIG Blueprints meeting. This issue is intended to capture the proposal and gather feedback before implementing the documentation improvements.
Summary
I'd like to propose improving the documentation for contributing Blueprints and Reference Implementations to make the existing contribution workflow clearer and easier to follow for new contributors.
While the current documentation explains how to submit a proposal, it doesn't describe the complete journey from proposal to merged documentation in a single place.
Motivation
The current documentation explains how to create a proposal issue, but it doesn't clearly describe what happens afterwards.
For example, a contributor could reasonably assume they should immediately open a pull request against the opentelemetry.io repository after creating a proposal issue. In practice, contributors are expected to wait until their proposal has been reviewed and approved by the Blueprints Team before opening a documentation PR.
Making this workflow explicit would help set clear expectations and reduce unnecessary work for both contributors and reviewers.
Proposed improvements
End User SIG repository
Add dedicated documentation describing the contribution workflow, for example:
These documents could describe:
OpenTelemetry documentation (opentelemetry.io)
Update the contributor guidance to reference the new contribution documentation by:
Implementation
If there is agreement on this proposal, I'd be happy to implement these documentation improvements and submit the corresponding pull requests to both the sig-end-user and opentelemetry.io repositories.
Background
This topic was discussed during the most recent End User SIG Blueprints meeting. This issue is intended to capture the proposal and gather feedback before implementing the documentation improvements.