search

jenkins-infra / jenkins.io

A static site for the Jenkins automation server
https://jenkins.io
Other
319 stars 1.21k forks source link

Installing Linux page has no upgrade instructions #5059

Open MarkEWaite opened 2 years ago

MarkEWaite commented 2 years ago

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:

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.

SahityaGupta25 commented 2 years ago

I Want to Work on this Issue

MarkEWaite commented 2 years ago

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:

SahityaGupta25 commented 2 years ago

I will Definitely join Docs office Hours.

MarkEWaite commented 2 years ago

Notes in Docs Office Hours recommended:

MarkEWaite commented 2 years ago

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.

SahityaGupta25 commented 2 years ago

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: @.***>

tanujdevops commented 1 year ago

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

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.

MarkEWaite commented 1 year ago

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:

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.

tanujdevops commented 1 year ago

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:

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.

SahityaGupta25 commented 1 year ago

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:

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: @.***>

krisstern commented 1 year ago

I would like to work on this issue for Hactoberfest, is anyone else still working on this?

Vandit1604 commented 1 year ago

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?

krisstern commented 1 year ago

Not sure if anyone is working on this

Vandit1604 commented 1 year ago

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 ?

MarkEWaite commented 1 year ago

Let's use a separate chapter. The "Installing" chapters are already long enough.

Vandit1604 commented 1 year ago

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

krisstern commented 1 year ago

Think so, that would be the most direct approach

krisstern commented 1 year ago

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.

Vandit1604 commented 1 year ago

Thanks for Clarification Alright then i'll start working

krisstern commented 1 year ago

You are welcome @Vandit1604! I will post the upgrading instructions for macOS here tomorrow Asia time.

krisstern commented 1 year ago

@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
Vandit1604 commented 1 year ago

@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

Vandit1604 commented 1 year ago

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

dduportal commented 1 year ago

@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

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.

krisstern commented 1 year ago

Agree @dduportal We will follow up on this in https://github.com/jenkins-infra/jenkins.io/pull/5888

Flamki commented 1 year ago

I want to work on this issues please assign me this

Vandit1604 commented 1 year ago

@Flamki I'm already working on this

Flamki commented 1 year ago

Yea you can carry on