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

Jump to bottom

[PROPOSAL] Host unreleased versions of the docs site #296

Closed
kavilla opened this issue Nov 24, 2021 · 5 comments
Closed

[PROPOSAL] Host unreleased versions of the docs site #296

kavilla opened this issue Nov 24, 2021 · 5 comments
Assignees
@Naarcha-AWS
Labels
Usability wontfix We will not address this issue due to complexity or invalidity.

Comments

@kavilla
Copy link
Member

kavilla commented Nov 24, 2021

What kind of business use case are you trying to solve? What are your requirements?

We have: https://opensearch.org/docs/1.2/dashboards/index/ which only came out for the 1.2 release. But when we bump our version for OpenSearch Dashboards, we would have to point to an older version of docs even thought the branches are accessible to the public.

What is the problem? What is preventing you from meeting the requirements?

https://github.com/opensearch-project/OpenSearch-Dashboards/blob/main/package.json#L15 is used by the docs service to point the links internally to the correct version of docs. For branches if we don't want potential 404s then we need to point older version of the docs or latest.

What are you proposing? What do you suggest we do to solve the problem or improve the existing situation?

Host the next upcoming release docs with some indication that it's unreleased so that we can point branches to that version for it's intended release.

What are your assumptions or prerequisites?

none

What are remaining open questions?

How to ensure not to make people confused for latest being "latest released".
@kavilla kavilla mentioned this issue Nov 24, 2021
Merged
7 tasks
@keithhc2 keithhc2 added the enhancement New feature or request label Jan 24, 2022
kavilla added a commit to kavilla/OpenSearch-Dashboards-1 that referenced this issue Mar 9, 2022
@kavilla
[Docs] update branch version to 1.3
b62b1d0 
`branch` in the package.json is used for pointing links to the right
site. For example: `https://opensearch.org/docs/1.3/dashboards/index/`.

NOTE: At the time this commit was made the doc site for `1.3`, is
not available.

There is an existing issue here:
opensearch-project/documentation-website#296

We can point this to `latest` but the problem with that is that we
don't re-release versions. When the next major or minor release
occurs then `latest` will point to that version and now all
OpenSearch Dashboards 1.3 downloads will point to the newest version.

So to avoid that, I suggest we point this to `1.3` and I got confirmation
that it will be `1.3`.

Issue resolved:
n/a

Signed-off-by: Kawika Avilla <kavilla414@gmail.com>
@kavilla kavilla mentioned this issue Mar 9, 2022
Merged
7 tasks
kavilla added a commit to opensearch-project/OpenSearch-Dashboards that referenced this issue Mar 9, 2022
@kavilla
[Docs] update branch version to 1.3 (#1333)
00e0693 
`branch` in the package.json is used for pointing links to the right
site. For example: `https://opensearch.org/docs/1.3/dashboards/index/`.

NOTE: At the time this commit was made the doc site for `1.3`, is
not available.

There is an existing issue here:
opensearch-project/documentation-website#296

We can point this to `latest` but the problem with that is that we
don't re-release versions. When the next major or minor release
occurs then `latest` will point to that version and now all
OpenSearch Dashboards 1.3 downloads will point to the newest version.

So to avoid that, I suggest we point this to `1.3` and I got confirmation
that it will be `1.3`.

Issue resolved:
n/a

Signed-off-by: Kawika Avilla <kavilla414@gmail.com>
@seanneumann
Copy link

Can we get this bumped up in priority?

@kavilla
Copy link
Member Author

kavilla commented Mar 16, 2022

Another issue: https://github.com/opensearch-project/documentation-website/blob/main/_clients/javascript.md

The NPM client is currently on 1.0.2 but main points https://opensearch.org/docs/latest/clients/javascript/ which points to https://opensearch.org/docs/1.2/clients/javascript/. This would confuse me because I would assume that I am reading the docs for JS client version 1.2.x.

@Naarcha-AWS Naarcha-AWS added the 1 - Backlog Issue: The issue is unassigned or assigned but not started label Jun 9, 2022
@Naarcha-AWS Naarcha-AWS self-assigned this Jun 9, 2022
@Naarcha-AWS Naarcha-AWS added this to the 2022-Q2 milestone Jun 9, 2022
@Naarcha-AWS Naarcha-AWS added Usability and removed enhancement New feature or request labels Jun 9, 2022
@hdhalter
Copy link
Contributor

@kavilla - can you please clarify? Is this still an issue? Thanks!

@kavilla
Copy link
Member Author

kavilla commented Mar 22, 2023

@kavilla - can you please clarify? Is this still an issue? Thanks!

@hdhalter yes I would assume so.

To clarify any documentation links added inline to components that don't exist in a previous release will basically be dead links. Take vis builder for example. Developers can't really include code that referenced: https://opensearch.org/docs/latest/dashboards/visualize/visbuilder/ until the version was released because the doc site only gets updated upon version release.

So if there was any code reference to the this link, developers would have to be okay with the 404 and re-route to so default route and verify on the day of release.

If the doc site followed the branching strategy that allowed for documentation to be hosted prior to release then in-application links to new docs can be verified prior to the day of release.

@hdhalter hdhalter removed this from the 2022-Q2 milestone Nov 10, 2023
@hdhalter hdhalter added wontfix We will not address this issue due to complexity or invalidity. and removed 1 - Backlog Issue: The issue is unassigned or assigned but not started labels Nov 22, 2023
@hdhalter
Copy link
Contributor

Hi @kavilla - I'm marking this as 'wontfix' due to having no bandwidth for fixing anything related to our branching strategy. If we move to a different architecture for our docs, we may be able to do something to solve this, but until then, I'm going to close this issue. In the meantime, if you come up with an easy solution and resources to apply it, please let me know. Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@Naarcha-AWS Naarcha-AWS

Labels
Usability wontfix We will not address this issue due to complexity or invalidity.
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
5 participants
@seanneumann @kavilla @keithhc2 @Naarcha-AWS @hdhalter