community
community copied to clipboard
open-telemetry
Migrate Mission page to opentelemetry.io
https://github.com/open-telemetry/opentelemetry.io/pull/1354 move the mission page to https://opentelemetry.io/mission/, to finalize https://github.com/open-telemetry/opentelemetry.io/issues/1289 this PR removes the mission-vision-values.md from this repo.
CC: @chalin
Can we add a link to the mission/vision/values from the community README? I liked how it was previously discoverable in the file tree and would like a link to be "above the fold" when a visitor arrives in the community repo.
Why do we need to move pages to .io? We're not moving the spec, it just gets copied, why can't we do that with all the community documents too?
Why do we need to move pages to .io?
From https://github.com/open-telemetry/opentelemetry.io/issues/833: "As a part of improving user experience and SEO, all OTel docs should be hosted on opentelemetry.io possibly aside from low-level technical notes and autogenerated docs (like API references) that require language-specific tools"
We're not moving the spec, it just gets copied, why can't we do that with all the community documents too?
The spec is synchronised on every release (so yesterday v1.11.0 was pulled), meaning that this has a clear cadence for getting updates and it also gives a "stable" view vs. the "in-flow" view of the github repo, which I personally find a nice feature.
I have no strict opinion on that topic. I think with the community docs it's not that easy (what's the cycle when they get updated from one place to the other?) and there is not a lot of advantages of having 2 places, so the main question is where do people look for that content?
@chalin, @austinlparker: thoughts?
Community repo is an established location with specific permissions and workflow. I think it should remain the authoritative source. The website can be synced via GH hook on every commit to trunk.
Why do we need to move pages to .io?
@svrnm explained it well (thanks!), the crux of it being the following:
From open-telemetry/opentelemetry.io#833: "As a part of improving user experience and SEO, all OTel docs should be hosted on opentelemetry.io possibly aside from low-level technical notes and autogenerated docs (like API references) that require language-specific tools"
As you can see from the opening comment of https://github.com/open-telemetry/opentelemetry.io/issues/833, considerable content has been moved, including entire doc suites, and more will be moved as a part of this consolidation effort. (AFAIK, there is broad acceptance with this mandate. If you disagree with the mandate, you're welcome to come present your arguments at the next Website/Comms meeting.)
We're not moving the spec, it just gets copied, why can't we do that with all the community documents too?
We host the entire spec on the website on every official release. We don't have that need for the community repo.
That being said, the scope of this PR is a single page. I'm not currently aware of other community repo pages that are targeted for migration. Can we proceed to wrap up the move of the Missions page @yurishkuro?
I have no issues with the objective of 833 of collating all documentation on the website. That objective does not require moving the original sources, only copying them. Removing files from the community repo is not something to be decided by the comms/website SIG, this repo is "owned" by the GC. I can raise this q at the next GC meeting.
I have no issues with the objective of 833 of collating all documentation on the website.
Great!
That objective does not require moving the original sources, only copying them.
Actually, we want each page to have a single source:
- https://github.com/open-telemetry/opentelemetry.io/issues/730
We've already cleanup up all duplication, we don't want to introduce any new instances.
Removing files from the community repo is not something to be decided by the comms/website SIG, this repo is "owned" by the GC. I can raise this q at the next GC meeting.
Fair enough. Thanks for raising the issue.
@yurishkuro - of course, if the GC feels strongly about it, the website repo can always git-submodule the community repo. As you pointed out earlier, this is what is done for the spec. It seems a little over the top for this repo -- for now we'd be linking in a single file -- but I can see how that might change over time.
I can understand how the GC might want to keep "ownership" and gating rights for changes to content contained in this repo. (Although, if the files are in the website repo, we can always setup CODEOWNERS over appropriate folders -- such as community.)
Looking forward to GC feedback, and thanks again for bringing this to the GC's attention.
Discussed in the GC call. GC recommendation is to use the same publishing mechanism for Community repo that we already use for including Specification into the website pages.
My personal suggestion: instead of using a submodule, use a web hook and pull the dependency repos at build time. This will eliminate the need for manual submodule hash updates and will keep the docs up-to-date with the Specs/Community automatically (one possible downside is if commits in those repos end up breaking the build of the website, e.g. by using invalid link).
I will close this ticket now and create a new ticket over at opentelemetry.io for the sync mechanism