Document how we update our docs

Currently our doc page is out-of-sync. current there is 1.12, but the latest release is 1.17.0 (which should be current)

The way the docs are currently updated is that we make a PR in https://github.com/elastic/docs - an example PR: https://github.com/elastic/docs/pull/2154.

Most APM Agent use a different approach: they set a specific branch in the APM Agent repo as current (let’s say 1.x) in the docs repo and for each agent release they just update their branch in the agent repo (in this case the 1.x branch) which will then include the current documentation.

The .NET Agent tries to be aligned on how docs are versioned with the overall stack docs, so on each minor (actually patch) release we need to update the docs repo as well. More on this in this PR: https://github.com/elastic/docs/pull/2066

Things which aren’t really clear and I’d like to clarify here:

• What files do we need to touch in https://github.com/elastic/docs when we release a new .NET agent version? You can see a few PRs here: https://github.com/elastic/docs/pulls?q=is%3Apr+dotnet+is%3Aclosed, which do the same changes across multiple files (I assume this has something to do with maintaining different versions). But it’s not clear what files we need to change. If we figure this out, I’ll document it in https://github.com/elastic/apm-agent-dotnet/blob/main/RELEASING.md. I’d like to have some clear rules around it, like: “If we release a new patch/minor/major .NET Agent version, then we need to update files X,Y,X (or some rule probably related to supported versions) in the docs repo”… or something similar, which we will then follow each time we release.
• Once it’s clear which files we need to update, I’ll open a PR to make our docs up-to-date.

@elastic/obs-docs @bmorelli25 Could you please help me to figure out the 1. point above? Happy to jump on zoom if needed.

[gregkalapos]

re: original question: huge thanks @bmorelli25 for the comment above.

With that, it’s now clear how this should work. We talked about this in our latest .NET syncs, and honestly no one was very convinced about how good this is compared to the way all other agents do it (which is to only have a single branch for each major version in the APM Agent repo and only link that).

I scheduled a meeting to discuss this - let’s talk about this over zoom.

[gregkalapos]

Hey @bmorelli25,

yeah, branches were not created, only the tags. I just created a branch based on the tag for the last release. So now we have the 1.17 branch.