Skip to content
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.

Sign up for GitHub

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

Update links #11923

Closed
wants to merge 2 commits into from
Closed

Update links #11923

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2793111
Update links
JStickler Feb 13, 2024
6690453
Merge branch 'main' into 2024.02.12_brokenLinks
JStickler Feb 13, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/sources/release-notes/cadence.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ weight: 1

## Stable Releases

Loki releases (this includes [Promtail](/clients/promtail), [Loki Canary](/operations/loki-canary/), etc) use the following
Loki releases (this includes [Promtail](https://grafana.com/docs/loki/latest/send-data/promtail/), [Loki Canary](https://grafana.com/docs/loki/latest/operations/loki-canary/), etc) use the following
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Loki releases (this includes [Promtail](https://grafana.com/docs/loki/latest/send-data/promtail/), [Loki Canary](https://grafana.com/docs/loki/latest/operations/loki-canary/), etc) use the following
Loki releases (this includes [Promtail](https://grafana.com/docs/loki/<LOKI_VERSION>/send-data/promtail/), [Loki Canary](https://grafana.com/docs/loki/<LOKI_VERSION>/operations/loki-canary/), etc) use the following

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I literally do not understand how there is any difference between specifying latest in the URL and specifying latest as the <LOKI_VERSION>. It's still "latest".

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Because these docs will also be in next and then they will link to latest instead of next.
And when you release the next version of Loki, the previous docs will also link to latest instead of linking within the current version.

You can choose to not use the <LOKI_VERSION> syntax but it will mean that you need to update your links as part of every release and it will negatively impact backporting.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Trying to think this through.... Going on what is currently documented in the Writers Toolkit, if the root _index/md file has LOKI_VERSION: latest then you still have the same problem of the links in next pointing to latest.

It isn't documented, but for links to resolve correctly wouldn't you need the following?
Latest release (Loki 2.9) -> _index/md file has LOKI_VERSION: latest?
Or even better, root _index/md file has LOKI_VERSION: 2.9?
Main branch -> root _index/md file has LOKI_VERSION: next?

Copy link
Member

@jdbaldry jdbaldry Feb 13, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

https://grafana.com/docs/writers-toolkit/write/shortcodes/#about-version-substitution

The shortcode substitutes the special syntax <SOMETHING_VERSION> with the version inferred from the page’s URL. If the page’s URL has the prefix /docs/grafana/latest/, the shortcode replaces the syntax <SOMETHING_VERSION> with latest in the final URL.

You can override version inference by including additional metadata in the front matter of the file. To override the value of <GRAFANA_VERSION>, set the GRAFANA_VERSION parameter in the page’s front matter. For example, to set the version to next irrespective of the source content version, add the following to the front matter: GRAFANA_VERSION: next.

If you don't set the front matter, the version is inferred from the page's URL

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The front matter override is primarily there so that other projects can specify the version of the documentation they are interested in linking to. For example, Grafana Cloud sets GRAFANA_VERSION: next so that all links to Grafana documentation go to the next version. The Mimir helm chart sets MIMIR_DOCS_VERSION to v2.10.x so that they can update a single place when the Mimir helm chart is updated to be compatible with a different version of Mimir and then all links point to the correct version of the Mimir docs.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you don't set the front matter, the version is inferred from the page's URL

The way that the Writers Toolkit is currently written tells you to set the value for the version in the root _index.md file. I would never have guessed that that was an optional step.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PRs are always welcome

naming scheme: `MAJOR`.`MINOR`.`PATCH`.

- `MAJOR` (roughly once a year): these releases include large new features and possible backwards-compatibility breaks.
Expand All @@ -18,14 +18,14 @@ naming scheme: `MAJOR`.`MINOR`.`PATCH`.
{{% admonition type="note" %}}
While our naming scheme resembles [Semantic Versioning](https://semver.org/), at this time we do not strictly follow its
guidelines to the letter. Our goal is to provide regular releases that are as stable as possible, and we take backwards-compatibility
seriously. As with any software, always read the [release notes](/release-notes) and the [upgrade guide](/upgrading) whenever
seriously. As with any software, always read the [release notes](https://grafana.com/docs/loki/latest/release-notes/) and the [upgrade guide](https://grafana.com/docs/loki/latest/setup/upgrade/) whenever
choosing a new version of Loki to install.
{{% /admonition %}}

New releases are based of a [weekly release](#weekly-releases) which we have vetted for stability over a number of weeks.

We strongly recommend keeping up-to-date with patch releases as they are released. We post updates of new releases in the `#loki` channel
of our [Slack community](/community/getting-in-touch).
of our [Slack community](https://grafana.com/docs/loki/latest/community/getting-in-touch/).

You can find all of our releases [on GitHub](https://github.com/grafana/loki/releases) and on [Docker Hub](https://hub.docker.com/r/grafana/loki).

Expand Down
Loading