-
-
Notifications
You must be signed in to change notification settings - Fork 1.4k
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
Use external hosting for javadocs (link from README/wiki) to reduce Git repo size #3440
Comments
Yes, Javadocs are hosted for new minor releases, to be linked to from project Wiki. I am ears for a better system, if this is an actual problem? (disk space is not super expensive these days) |
No maintainer experience to offer but I've used readthedocs.io many times I'm betting you haven't seen this https://www.javadoc.io/doc/com.fasterxml.jackson.core/jackson-databind/latest/index.html
|
Ok, I think we might already have a link from README to external Javadocs; those that are based on Javadoc Maven bundles from Maven Central. So that could significantly simplify changes. But I think one thing that would allow dropping addition of new javadocs (existing one probably need to be kept at least for a while in case someone is linking to them?) would just be changing of links from Wikis to external Javadoc providers for specific version. I think this would be a great "new contributor" task to check. |
Unsure who would be linking to GH javadocs but I wouldn't encourage it by doing anything other than purging them. No one will thank you for keeping their Medium article hotlinked (or ever change those links). My own experience is that, with modern IDEs fully automating |
To keep this one vaguely moving - would you be against me going through each |
Yes; if you could first replace links on Wiki: https://github.com/FasterXML/jackson-databind/wiki that'd be a good step (I think you have access, if not LMK). And I guess simple redirecting docs for Help much appreciaed @drekbour ! |
👍 Updated wiki for jackson-core, jackson-databind I note that, because javadoc.io has a drop down covering all versions, the new links are generic and need no maintenance. This leads me to think they could be added to the README.md? |
Thank you @drekbour! README already actually has the Javadocs badge under "Status". How about annotations' wiki? Ah already done too, great! :) |
Removed
|
@drekbour I changed access settings so you should be able to change wikis for:
LMK which other ones you'd want to target. |
FYI: these changes break the builds of some downstream projects. For example, the Spring Framework 6.0.x build was broken by this. I have not investigated which further builds are broken, but I imagine there could be many. The reason these changes break builds is that some projects configure Jackson for external Javadoc links. For example, in the Spring Framework builds we were configuring the following external links.
When the
Navigating up that directory structure led me to https://fasterxml.github.io/jackson-core/ which states:
That's how I eventually found this GitHub issue. To fix Spring's builds, I got things working again by using However, as a benefit to the Jackson community it would be great if you could introduce redirects from URLs such as https://fasterxml.github.io/jackson-core/javadoc/2.10/package-list to https://www.javadoc.io/doc/com.fasterxml.jackson.core/jackson-core/2.10.0/package-list. FWIW, I noticed that you mentioned adding redirects for |
The Jackson project no longer publishes Javadoc at https://fasterxml.github.io which breaks the `javadoc` and `api` build tasks due to their dependency on that web site for external Javadoc links. As a workaround, we now reference Jackson's Javadoc via https://www.javadoc.io. See FasterXML/jackson-databind#3440 Closes gh-29894
The Jackson project no longer publishes Javadoc at https://fasterxml.github.io which breaks the `javadoc` and `api` build tasks due to their dependency on that web site for external Javadoc links. As a workaround, we now reference Jackson's Javadoc via https://www.javadoc.io. See FasterXML/jackson-databind#3440 Closes gh-29895
Thank you for bringing this to our attentiont @sbrannen . Ugh. My intention was not break things in this way, and in hindsight I should have asked about possible downside on user/dev mailing list. I would need help in figuring out a good way to resolve things here: undoing removals is a possibility, which would mean doing something like:
But if redirect works, that's better, I assume this: https://blog.hubspot.com/website/html-redirect would do the trick? Although not sure about redirecting |
I'm not sure if html redirects using meta tags supports wildcards. One approach that does are |
@pjfanning That sounds like a good solution where feasible Not sure it is doable here since we rely on Github pages/in-repo docs reference. But then again we can't be the first project to hit issues like this... |
This also broke our pipelines and I imagine lots of other people's pipelines. The older URL no longer exists even for older versions. It would have make more sense to keep the URL around for some time. |
@joca-bt broken pipelines are esy to fix - eg spring-projects/spring-framework@40d2466 We may put back the old pages but first, we want to see if we can use redirects instead. Unfortunately, if you need an immediate fix, then you are stuck with changing the URL in your own build files like the spring commit above. |
But given there was no announcement anywhere about this, you are making user's life more difficult for literally no reason. The old website is just broken, as it shows 404. At least we could add a banner saying "The javadoc has moved to ..." so users don't need to guess. |
It's not my repo. I didn't make the change. The change wasn't made to ruin your day. There is an announcement on https://fasterxml.github.io/jackson-databind/ It just wasn't considered that users link to the subpages in their builds. But to reiterate, the javadocs are accessible at https://www.javadoc.io/doc/com.fasterxml.jackson.core/jackson-databind |
@joca-bt This was not intentional: I was not sure there was actual usage. But yes, this definitely could have gone better. At this point I am looking for best solutions to achieve what we want (reduced size of repo download, less maintenance; but also trying to avoid breakage by existing users). PR would be good, or proposal for revert, followed by selective removal: for example, retain versions 2.10.x and later, do not publish version 2.15 and later. |
Reading through earlier comments, it sounds like Second, assuming |
Hi @cowtowncoder, Thanks for investigating ways to alleviate the issues. When I originally reported the issue about broken builds, I was only focusing on getting builds to work going forward; however, that is only part of the overall set of issues. It's actually considerably more involved. Let me see if I can highlight the issues I'm aware of. Restoring For example, if I revert those changes I made to Spring's build (i.e., switch back to using external Javadoc links like Concrete examples:
The latter bullet point is applicable not only to the published Javadoc of numerous (thousands?) of libraries/projects around the world, but it also applies to any published blog, tweet, Stack Overflow answer, etc. in which somebody included a link to a specific version of Jackson's Javadoc. Just to be clear, Spring's 6.0.5-SNAPSHOT Javadoc does not have broken links to Jackson because the I hope that clarifies the scope of the issues, but to summarize:
I see the following as possible options.
Looking forward to hearing what you decide. Cheers, Sam |
3 is great but so far no solution that works has been found. It might be possible to do 1 but change the branch that is used - GitHub pages config would need to be changed to use the separate branch. This approach keeps the master and 2.x branches small. |
If you believe this answer to be the authoritative answer, then the answer is that it is (currently) impossible to configure a 301 redirect with GitHub Pages. However, it does appear to be possible by setting up CNAME redirection for a custom domain, but I'm not sure if that's feasible/appropriate/possible for Jackson. |
@cowtowncoder if it's ok with you, I can create a ghpages branch based off 2.14 branch prior to the recent docs for changes. See my previous comment. Changing the GitHub repo settings to use the ghpages branch is a simple change in Settings tab. |
Hmmh. It's too bad I moved out of gh-pages earlier, but I am not opposed to going back there I suppose. So +1 for that @pjfanning . |
Thank you @sbrannen for a very thorough explanation why the "quick patch" won't be enough. I think @pjfanning's idea of going back to gh-pages makes sense, so let's plan on doing that. And we can still leave project Wiki links pointing to |
I've overwritten gh-pages for jackson-core and jackson-databind so the javadocs for those 2 projects are back.
also now: |
Excellent @pjfanning, thank you for doing this. |
It makes "global search" harder when navigating the project in IDE. WDYT of having a separate repository (e.g. fasterxml-javadoc.github.io/...) that would host the generated javadocs? |
We have moved to not publishing Javadocs within repo any more, links pointing to https://www.javadoc.io/doc/com.fasterxml.jackson.core/jackson-databind where Javadocs are probably extracted from Maven Central, to where we release process publishes them. So I will close this as done. Individual repositories still mostly have their old Javadocs which we probably do not want to remove. |
I can't figure out why the javadocs are saved into the source-tree. I really can't understand why the full record of historic javadocs is stored there. It is about 60x the size of the
/src
tree!I presume this is so GH hosts these but isn't there a better way?
The text was updated successfully, but these errors were encountered: