jenkins.io
jenkins.io copied to clipboard
jenkins-infra
Installing Linux page has no upgrade instructions
Problem with the Installing Linux page, source file
Linux install guide lacks upgrade instructions
The page describes the installation process but does not describe the upgrade process. Multiple Linux users have performed the initial installation with the Linux package manager for their Linux operating system, then made the mistake of upgrading by replacing the jenkins.war file with a newer file.
Some examples of the mistake include:
- Jenkins init.d not parsing JDK version correctly on community.jenkins.io
- LTS Jenkins upgrade from 2.263.4 to 2.319.3 on community.jenkins.io
- Jenkins startup times out on community.jenkins.io
Possible Solution
We should state clearly that Jenkins upgrades of Linux packages should be done with the Linux package manager, not by replacing the jenkins.war file.
Thanks @SahityaGupta25 . I'd like a discussion in Docs Office Hours (Asia) about the placement of the upgrade instructions. I'm not sure if it is better to have:
- New User Handbook chapter "Upgrading Jenkins" at the same level as "Installing Jenkins"
- Add "Upgrading" section to each of the sections of installing like "Docker", "Linux", "WAR files", and "Windows"
- Some other technique
Notes in Docs Office Hours recommended:
- rename “Installing Jenkins” to “Install & Upgrade”
- Guide user to upgrade only the Jenkins package with package manager
- Refer them to their operating system guide for wider upgrades
- Add upgrade section to each location (Linux, Windows, Docker, etc.)
- Start small, add to just one Linux, submit PR
See https://community.jenkins.io/t/how-to-upgrade-java-for-jenkins-on-windows-10/2121 for another example of an open question asking for more details on upgrading Jenkins.
Sorry Mark I was Busy in My Youtube Channel. https://www.youtube.com/channel/UCTR9St_x13OBvo4WXv2nkdw
On Sun, 17 Apr 2022 at 00:58, Mark Waite @.***> wrote:
See https://community.jenkins.io/t/how-to-upgrade-java-for-jenkins-on-windows-10/2121 for another example of an open question asking for more details on upgrading Jenkins.
— Reply to this email directly, view it on GitHub https://github.com/jenkins-infra/jenkins.io/issues/5059#issuecomment-1100738439, or unsubscribe https://github.com/notifications/unsubscribe-auth/AXT6BNUBWQMCFEZZGUPIWETVFMIEZANCNFSM5S5IBTNQ . You are receiving this because you were mentioned.Message ID: @.***>
Notes in Docs Office Hours recommended:
rename “Installing Jenkins” to “Install & Upgrade”
- Guide user to upgrade only the Jenkins package with package manager
- Refer them to their operating system guide for wider upgrades
- Add upgrade section to each location (Linux, Windows, Docker, etc.)
Start small, add to just one Linux, submit PR
I was looking at the resources for upgrading Jenkins package on Linux using package manager, The upgrade instructions will differ depending on the distribution of Linux, as there are different package managers for different Linux distributions. As we see on our Linux Installation page, we have mentioned
- Debian/Ubuntu
- Fedora
- RedHat/CentOS
And we have provided installation instructions for these distributions individually, it would make more sense for the Upgrade section to also have the upgrade instructions for each distribution individually.
I am looking forward for a follow up on this so that I can start working on the same.
I think that the focus of the user during installation is very different from the focus of the user during upgrade. I think that the amount of instruction needed to describe an upgrade is at least as much as the instruction needed to describe an upgrade. I think that the pattern in other documentation sets is to have install and upgrade as separate sections. Some examples include:
- FreeBSD install (chapter 2) and upgrade (chapter 24)
- Ubuntu install guide and upgrade guide
- Red Hat 8 install guide and upgrade guide
I think we should have a separate chapter dedicated to upgrade, with a heading per operating system as we do for the installation guide.
I'll need to review the notes of the Docs Office Hours to understand what motivated the recommendation to place the upgrade instructions on the same page as the installation instructions. They are very different tasks at very different points in the administrator's experience.
I think that the focus of the user during installation is very different from the focus of the user during upgrade. I think that the amount of instruction needed to describe an upgrade is at least as much as the instruction needed to describe an upgrade. I think that the pattern in other documentation sets is to have install and upgrade as separate sections. Some examples include:
- FreeBSD install (chapter 2) and upgrade (chapter 24)
- Ubuntu install guide and upgrade guide
- Red Hat 8 install guide and upgrade guide
I think we should have a separate chapter dedicated to upgrade, with a heading per operating system as we do for the installation guide.
I'll need to review the notes of the Docs Office Hours to understand what motivated the recommendation to place the upgrade instructions on the same page as the installation instructions. They are very different tasks at very different points in the administrator's experience.
That sounds reasonable. Do let me know what decision is being taken, I will start working accordingly.
You can start working on it.
On Mon, 3 Oct 2022, 2:36 pm tanujdevops, @.***> wrote:
I think that the focus of the user during installation is very different from the focus of the user during upgrade. I think that the amount of instruction needed to describe an upgrade is at least as much as the instruction needed to describe an upgrade. I think that the pattern in other documentation sets is to have install and upgrade as separate sections. Some examples include:
- FreeBSD https://docs.freebsd.org/en/books/handbook/cutting-edge/ install (chapter 2) and upgrade (chapter 24)
- Ubuntu install guide https://help.ubuntu.com/20.04/installation-guide/amd64/index.html and upgrade guide https://ubuntu.com/server/docs/upgrade-introduction
- Red Hat 8 install guide https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/performing_a_standard_rhel_8_installation and upgrade guide https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/upgrading_from_rhel_7_to_rhel_8
I think we should have a separate chapter dedicated to upgrade, with a heading per operating system as we do for the installation guide.
I'll need to review the notes of the Docs Office Hours to understand what motivated the recommendation to place the upgrade instructions on the same page as the installation instructions. They are very different tasks at very different points in the administrator's experience.
That sounds reasonable. Do let me know what decision is being taken, I will start working accordingly.
— Reply to this email directly, view it on GitHub https://github.com/jenkins-infra/jenkins.io/issues/5059#issuecomment-1265147676, or unsubscribe https://github.com/notifications/unsubscribe-auth/AXT6BNURCHACDNCZRLLTEKLWBKO2HANCNFSM5S5IBTNQ . You are receiving this because you were mentioned.Message ID: @.***>
I would like to work on this issue for Hactoberfest, is anyone else still working on this?
Hey i'd like to work on this what was the decision taken for upgrading jenkins according to OS will it have its own dedicated chapter or 'Installing Jenkins' will be renamed to 'Install and Upgrade' with section added for upgrade?
I would like know if i have to start working on this do i have to create a new chapter for upgrading jenkins Or add a section in "installing jenkins" chapter ?
Let's use a separate chapter. The "Installing" chapters are already long enough.
So do i need to create a new folder named 'updating' and add updating steps for all the OS and tools on which jenkins can be used? I only know how to update Jenkins in Linux and in Windows if can be updated from the UI itself ? Can you clarify a bit more
You can add the instructions for Linux and Windows first, if need be I can add the remaining details for macOS, or provide you with the details here so you could complete the PR.
You are welcome @Vandit1604! I will post the upgrading instructions for macOS here tomorrow Asia time.
@Vandit1604, here are the instructions for macOS:
To upgrade the Jenkins LTS on macOS, do the following at the terminal with homebrew:
brew update && brew install jenkins-lts
Similarly, to upgrade the Jenkins Weekly on macOS, do the following at the terminal:
brew update && brew install jenkins
@krisstern thanks for the big help i was wondering the procedure to add images if i want to add an image on a page i checked the Contributing.adoc but couldn't able to find the procedure to add images
hey @krisstern can you please help me with why the checks failing? is this because i have added new images ? i followed the steps from contributing.adoc
@Vandit1604, here are the instructions for macOS:
To upgrade the Jenkins LTS on macOS, do the following at the terminal with
homebrew:brew update && brew install jenkins-ltsSimilarly, to upgrade the Jenkins Weekly on macOS, do the following at the terminal:
brew update && brew install jenkins
Are we still supporting macOS? As far as I can tell, we do not and the homebrew installation is managed by someone else. If that is the case, I vote for not documenting OR pointing out to the external homebrew documentation. Otherwise we'll risk giving false expectations and falsy instructions.
Agree @dduportal We will follow up on this in https://github.com/jenkins-infra/jenkins.io/pull/5888
