[semconv] Publish HTTP migration plan

[TylerHelmuth]

I was looking through https://opentelemetry.io/blog/2023/http-conventions-declared-stable/ and it is a really good blog post, but I am worried about its discoverability in the future. I think it would be a better user experience to create a dedicated, permanent place on the site specifically for semconv breaking change migration plans. I feel this will improve end user's understanding of the changes they'll be dealing with as they update queries, boards, alerts, etc.

Closely related to open-telemetry/semantic-conventions#534

[svrnm]

I think that's a good idea, where should we position that? Right now we have no place for the semantic conventions outside the "Concept" page at https://opentelemetry.io/docs/concepts/semantic-conventions/, would this be a place to include that or should we build a different place?

[TylerHelmuth]

I'm not entire sure where it should live. Can we rely on something being published in the semconv repo and then using https://opentelemetry.io/docs/specs/semconv/? Or maybe we can nest something inside https://opentelemetry.io/docs/instrumentation/?

[chalin]

Yes, if the (future) migration page(s) are a part of the semconv repo, we can publish them here. How about a migration folder under https://github.com/open-telemetry/semantic-conventions/tree/main/docs? Such a folder would naturally appear under https://opentelemetry.io/docs/specs/semconv/.

And/or we could add the migration pages under https://opentelemetry.io/docs/migration/:

If y'all prefer to have opentelemetry.io/docs/specs/semconv/migration, then we could add an alias it to opentelemetry.io/docs/migration/semconv, for example.

[cartermp]

I would prefer to have the migration pages under the /migration subfolder rather than in the spec. Migration is an end-user concern.

Well, unless the only docs are about how SDKs should consideration migrating. I'd want to have something written anyways for end-users if that's the case.