-
Notifications
You must be signed in to change notification settings - Fork 183
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Renamed specification
and semantic_conventions
directories for more clarity
#161
Renamed specification
and semantic_conventions
directories for more clarity
#161
Conversation
2931833
to
5c041e3
Compare
(Never use the word "final" with software-related projects... #158) I would suggest to instead rename the "specification" top-level directory to "semantic_conventions". EDIT: Oh, that name is already taken. Maybe a different one could be found for the YAML directory, the current one has lead to confusion in the past already. Since this repository is now only about the conventions, maybe name it |
Very true! :-D |
specification
and semantic_conventions
directories for more clarity
6e819d2
to
8273e98
Compare
@Oberon00 Pushed a commit with your proposal. This makes it a huge change (touching many files). What do others think, should we do that change now? If not I can revert the last commit. |
I like the idea with I even found myself open the |
If we are going to go ahead with this change I'd propose doing so asap and also before we release the first version from this repo. This way we only cause the pain and churn of breaking all the links once since incoming links will already need to be updated from the spec repo to this one anyway, then the changed paths on top don't make it much worse now but they would do so later. |
@arminru I'm with you that we either need to do this change ASAP to avoid causing more pain or delay it until later. Originally, to avoid too much churn all at once, I wanted to delay on this aspect and just focus on refactoring the human-readable structure and website. @chalin FYI - If this PR is adopted and merged, we'll need to (hopefully not dramatically) change the website integration at that point. @AlexanderWert Can you split out the change |
@chalin will we need to rename the folder where the markdown files are to |
@joaopgrassi @jsuereth - yes, I'd vote to name the docs folder |
So far we have been already using semantic_conventions. I would slightly prefer that over "docs" because they are not documentation of the conventions, but the actual conventions. |
@Oberon00 Right now the |
Here's my reasoning:
That being said, which ever name y'all choose, we'll be able to publish it on the OTel website. So the choice is yours. |
@jsuereth If we want to eventually rename the In several other OTel repos there are many references to the |
Even better IMHO, would be to change those links to refer to the OTel website semconv pages, once those land. That way we can gracefully handle page renames via redirects. |
I created an alternative PR with a renaming to |
I think we should definitely rename the yaml directory to something other than semantic_conventions. Everything else, I have no strong opinion on. We could even consider moving everything inside the current specification/ directory one level up and move most of the other files there to a new subdirectory. (Since I just noticed it, there is also the issue of the supplementary-guidelines directory which was split out because it is not "specification". An issue that might not apply anymore if we decide to rename "specification" to anything else. I think it would be best to move these files back together, but I already suggested not splitting them in the first place in open-telemetry/opentelemetry-specification#3212 (comment). This can be done even after the release though, since I doubt there are many links to that directory) |
Signed-off-by: Alexander Wert <[email protected]>
8273e98
to
6378732
Compare
Want to bring another aspect here |
@AlexanderWert Yeah, those document references, ideally, will move to opentelemetry.io over time where we can better stabilize the URLs, as @chalin points out. I really like #166, so I'd vote for making these changes now before release and fixing this quickly. I'll set aside more time in the AM tomorrow to kick of cleanup. |
Summary of changes:
semantic_conventions
sub-dir in theresource
directorysemantic_conventions
directory tomodel
(that's the one containing the yaml files)specification
directory tosemantic_conventions
(that's the one containing the.md
files)