Docs-website: Current release note file naming convention has chance of duplication

[michaelgoin]

Description

Is this really a bug? Not really but wanted to raise a concern that may not have any technical impacts but may cause a little bit of thrash/confusion in the future.

Currently, the release-note naming convention (at least for agents) includes the version with all periods/dots removed. For example, v7.1.3 will map to the file: node-agent-713.mdx.

The problem is, different variations of double-digit version in the major, minor or patch locations could result in overlap.

v11.9.2 VS v1.19.2 both consolidate down to 1192. Or v4.11.1 and v4.1.11 both consolidate to 4111 based on the current conventions in place.

Obviously a few ways you could go but one potential more future-proof convention would be to use '-' to replace the '.' for the version numbers.

So v4.11.1 would become node-agent-4-11-1.mdx and v4.1.11 would become node-agent-4-1-11.mdx.

Overall, quite minor but may reduce questions in the future if handled differently.

Steps to reproduce

N/A

Expected behavior

Ideally, no chance of overlap.

[jpvajda]

@michaelgoin would you like to correct this? 😄 We can point you to where this is controlled. cc @jerelmiller

[michaelgoin]

@jpvajda Sure thing. Happy to help make it happen.

[jerelmiller]

I'll leave the decision up to the docs team, but I think this is a great idea going forward. Not sure we necessarily need to update all the previous release notes at this point. This is a great observation though!

[jpvajda]

@jerelmiller agreed, I don't think going back and correcting every file name is required either. So these seems like it's more of a naming convention process we'd want to communicate to agent teams. @austin-schaefer thoughts?

You can see a sample of the files here: https://github.com/newrelic/docs-website/tree/develop/src/content/docs/release-notes/agent-release-notes/c-sdk-release-notes

But I guess we'd need to change how the release notes component generates the title of the note based on the naming convention. Though if we do that wouldn't the file names need to change for all old notes?

[jerelmiller]

But I guess we'd need to change how the release notes component generates the title of the note based on the naming convention

We shouldn't need to! We have both the subject and the version in front matter. The title is derived from those 2 fields, not from the doc file name, so no need to change anything. The file name itself only influences the URL for the release note, nothing else.

[michaelgoin]

This worked out, as described, via: https://github.com/newrelic/docs-website/pull/1515.

Is there any documentation we should put in place to encourage a different convention going forward? I'll likely convert a chunk of ours at some point so there's a clear "this is what we are doing now" example.

I'll also give agent teams a heads up, but that reach is obv limited to that group.

[jpvajda]

@michaelgoin Thanks for testing this out! it's great to know it works ok with the - between the versioning numbers, I'll defer to the Docs Team how they want to document this formatting option as they have a very detailed style guide that this may be a good place to document this concept. @paperclypse / @austin-schaefer what do you think? Essentially you can use either format of an agent version numbering schema and by using the - you avoid the problem outlines in this issue.

[michaelgoin]

In a slack thread with @austin-schaefer I agreed to update the style guide here: https://docs.newrelic.com/docs/style-guide/article-templates/create-release-notes/.

When I get a PR in for that, I'll set it up to close this issue.

Thanks all!

[jpvajda]

@michaelgoin that's awesome! We appreciate the contributions to this process!