-
Notifications
You must be signed in to change notification settings - Fork 788
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
Proposal: Versioning of Documentation #2349
Conversation
docs/.vscode/settings.json
Outdated
@@ -0,0 +1,6 @@ | |||
{ |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is this file introduced intentionally? I don't think should be commited.
1. Version Documentation. | ||
2. Add or remove necessary and unnecessary data from it. | ||
3. Organize the documentation so that it's easily understandable. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think we're trying to address too much in this proposal. We should get stick to our goal: having a way to version part of the documentation (the one which is expected to change version-by-version, like config file).
The idea is to use a tool to organize current documentation. Prometheus uses netlify. | ||
Rucio uses Sphinx. Other tools like Github Pages |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think the following section is focusing on the wrong problem. We don't want to change how the website is built or deployed (unless strictly required, but let's say we should try to avoid it as much as possible), while we should focus the discussion on:
- Which pages do we want to version?
- For which versions we want to add a new versioning? Major, minor or patch version? I would say we want versioning for minor version (ie.
1.0
,1.1
, ...) - How do we manage the versioning at website build time? How do we build the config for the version
1.0
,1.1
, ... over the time?
|
||
## Problem | ||
|
||
In Cortex, documentation needs a lot of reordering. The idea is to have version documentation just like Prometheus.[`Prometheus`](https://prometheus.io/docs/introduction/overview/). Documentation is the main source of information for current contributors and first-timers. A properly versioned documentation will help everyone to have a proper place to look for answers before flagging it in the community. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What do you mean by "reordering" here?
4. Supports custom domains. | ||
|
||
#### Cons | ||
1. Currently, there is no support for HTTPS for custom domains. It’s probably coming soon though. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
HTTPS for custom domains works for some time now (I use it myself for at least a year)
Thanos is also going to address the same (see thanos-io/thanos#2488). @jaybatra26 Are you still interested into working on this? Otherwise I guess we can close the proposal because stale. |
@pracucci I am, lemme rewrite the proposal and come back to you in a few hours. |
455c298
to
ac46fae
Compare
Let's start a discussion about how to version documenation. I have listed a few tools that can be used with their respective pros and cons. Signed-off-by: Jay Batra <jaybatra73@gmail.com>
Updates the proposal as per discussion on slack. Signed-off-by: Jay Batra <jaybatra73@gmail.com>
Signed-off-by: Marco Pracucci <marco@pracucci.com>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks Jay! LGTM 🎉
FYI, I've just pushed a commit to fix the markdown layout and mention that the "running-cortex" URL path segment may change during implementation.
Thanks for the input @pracucci. I sincerely appreciate it. |
Signed-off-by: Marco Pracucci <marco@pracucci.com>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Definitely we are doing the same thing here as thanos-io/thanos#2488
BTW We plan this to be Summer of Code project 🤗
Thanks @jaybatra26 for ping!
cc @pracucci
3. Include the master version and last 3 minor releases. Documentation defaults to the last minor release. | ||
|
||
|
||
## Proposed solution |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Makes sense... but how? 😄
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The goal of this proposal is primarily to get consensus about which pages should be versioned and how it should from the user-perspective. We decided that implementation details will be discussed deeper during the implementation phase (so that me and Jay can get a faster feedback loop, once we got consensus about versioning doc).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@bwplotka Currently we use Docsy theme of HUGO. It allows versioning.
This is the gist of where we can start with.
https://www.docsy.dev/docs/adding-content/versioning/#adding-a-version-drop-down-menu
|
||
1. Version specific pages of the documentation | ||
2. Include links to change version (the version must be in the URL) | ||
3. Include the master version and last 3 minor releases. Documentation defaults to the last minor release. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Why not keep docs for all released minor versions? I have occasionally found it useful to be able to find very old (10-15 years) documentation for some projects, but if cost (in terms of maintainance, work, ...) is prohibitive, then let's not do that.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Good feedback. Given the fast pace of Cortex and that we just cut the first stable release, I was wondering if it's healthy to keep the doc for very old versions, considering we want people to use recent versions. But I don't feel strong about this, and at the end the number of versions to keep will just be a configuration option in the website generation.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM, having quick access to old versions of documentation is useful at times.
A properly versioned documentation will help everyone to have a proper place to look for answers before flagging it in the community.
If only...
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM!
I think enough time has passed to eventually let other maintainers look at this. Considering this is not a core feature (even if important for the user UX) let's consider the proposal approved and move on with the implementation @jaybatra26 🎉 |
Thanks, @pracucci . I have started working on it. :) |
What this PR does:
Let's start a discussion about how to version documenation.
I have listed a few tools that can be used with their respective
pros and cons.
Which issue(s) this PR fixes:
Fixes #
Checklist
CHANGELOG.md
updated - the order of entries should be[CHANGE]
,[FEATURE]
,[ENHANCEMENT]
,[BUGFIX]