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

don't use 'current' for doc links #808

Merged
merged 2 commits into from
Sep 18, 2024
Merged

don't use 'current' for doc links #808

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ce3c9bf
don't use 'current' for doc links
pjfanning Sep 16, 2024
523ee24
use sbt-pekko-build support for getting x.y version
pjfanning Sep 18, 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
2 changes: 1 addition & 1 deletion build.sbt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -392,7 +392,7 @@ lazy val docs = project
"hadoop.version" -> Dependencies.HadoopVersion,
"extref.github.base_url" -> s"https://github.com/apache/pekko-connectors/tree/${if (isSnapshot.value) "main"
else "v" + version.value}/%s",
"extref.pekko.base_url" -> s"https://pekko.apache.org/docs/pekko/current/%s",
"extref.pekko.base_url" -> s"https://pekko.apache.org/docs/pekko/${Dependencies.PekkoBinaryVersion}/%s",
Copy link
Member

Choose a reason for hiding this comment

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

Now that I think about it more, I'm no longer sure that it's better to link to the the Pekko version this is built against than the 'current' Pekko version: because of binary compatibility it'll be common and recommended that people use newer versions of Pekko with older versions of satellite libraries.

I'm not opposed though :)

Copy link
Contributor Author

Choose a reason for hiding this comment

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

The idea is to point to the docs of the lib based on the version of that lib that we build with. As we have seen with the Pekko core docs and the redirect of current from 1.0 to 1.1 broke some links. This approach of not linking to current means things are more stable.

Copy link
Member

Choose a reason for hiding this comment

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

As we have seen with the Pekko core docs and the redirect of current from 1.0 to 1.1 broke some links

I think we should avoid that in the future by leaving behind redirects, though: while changing our own sites to link to specific version indeed avoids some breakage, there might still be external links pointing to 'current'. It might also be better for SEO. Additionally, in Akka we often noticed people being confused because they were referring to outdated versions of the docs.

Having said that, I'm still OK with the change to the versioned docs - just wanted to share my thoughts for consideration.

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've already pushed similar changes into other Pekko repos so I would like to stay consistent. We can always review the strategy again later.

The Akka docs have a feature to warn you if you are viewing old docs and provides a link to the latest docs. We could try to do something similar. One approach would be for legacy branches (eg 1.0.x branches) to be modified to put a header on all pages that provides a link to the current version of that page.

"scaladoc.org.apache.pekko.base_url" -> s"https://pekko.apache.org/api/pekko/${Dependencies.PekkoBinaryVersion}",
"javadoc.org.apache.pekko.base_url" -> s"https://pekko.apache.org/japi/pekko/${Dependencies.PekkoBinaryVersion}/",
"javadoc.org.apache.pekko.link_style" -> "direct",
Expand Down
4 changes: 2 additions & 2 deletions project/Dependencies.scala
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ object Dependencies {
val ScalaVersions = Seq(Scala213, Scala212, Scala3)

val PekkoVersion = PekkoCoreDependency.version
val PekkoBinaryVersion = PekkoVersion.take(3)
val PekkoBinaryVersion = PekkoCoreDependency.default.link

val InfluxDBJavaVersion = "2.23"

Expand All @@ -32,7 +32,7 @@ object Dependencies {
val PekkoGrpcBinaryVersion = "1.1"
val PekkoHttpVersion = PekkoHttpDependency.version
val PekkoStreamsCirceVersion = "1.1.0"
val PekkoHttpBinaryVersion = "1.0"
val PekkoHttpBinaryVersion = PekkoHttpDependency.default.link
val ScalaTestVersion = "3.2.19"
val TestContainersScalaTestVersion = "0.41.4"
val mockitoVersion = "4.11.0" // check even https://github.com/scalatest/scalatestplus-mockito/releases
Expand Down
Loading