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

Installing Linux page has no upgrade instructions #5059

Open
MarkEWaite opened this issue Apr 8, 2022 · 28 comments · May be fixed by #5888
Open

Installing Linux page has no upgrade instructions #5059

MarkEWaite opened this issue Apr 8, 2022 · 28 comments · May be fixed by #5888
Labels
bug

Comments

@MarkEWaite
Copy link
Contributor

MarkEWaite commented Apr 8, 2022 •
edited

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.
@MarkEWaite MarkEWaite added the bug label Apr 8, 2022
@MarkEWaite MarkEWaite changed the title Instaling Linux page - no upgrade instructions Installing Linux page - no upgrade instructions Apr 8, 2022
@MarkEWaite MarkEWaite changed the title Installing Linux page - no upgrade instructions Installing Linux page has no upgrade instructions Apr 12, 2022
@SahityaGupta25
Copy link

I Want to Work on this Issue

@MarkEWaite
Copy link
Contributor Author

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

@SahityaGupta25
Copy link

I will Definitely join Docs office Hours.

@MarkEWaite
Copy link
Contributor Author

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

@MarkEWaite
Copy link
Contributor Author

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
Copy link

SahityaGupta25 commented Apr 24, 2022 via email

@tanujdevops
Copy link
Contributor

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.

@MarkEWaite
Copy link
Contributor Author

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
Copy link
Contributor

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
Copy link

SahityaGupta25 commented Oct 3, 2022 via email

@krisstern
Copy link
Member

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

@Vandit1604
Copy link
Contributor

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
Copy link
Member

Not sure if anyone is working on this

@Vandit1604
Copy link
Contributor

Vandit1604 commented Dec 28, 2022 •
edited

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
Copy link
Contributor Author

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

@Vandit1604
Copy link
Contributor

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
Copy link
Member

Think so, that would be the most direct approach

@krisstern
Copy link
Member

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
Copy link
Contributor

Thanks for Clarification
Alright then i'll start working

@krisstern
Copy link
Member

krisstern commented Jan 6, 2023 •
edited

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

@krisstern
Copy link
Member

@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
Copy link
Contributor

Vandit1604 commented Jan 7, 2023 •
edited

@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 Vandit1604 linked a pull request Jan 7, 2023 that will close this issue
Open
@Vandit1604
Copy link
Contributor

Vandit1604 commented Jan 7, 2023 •
edited

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
Copy link
Contributor

@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
Copy link
Member

Agree @dduportal We will follow up on this in #5888

@Flamki
Copy link

Flamki commented Jan 20, 2023

I want to work on this issues please assign me this

@Vandit1604
Copy link
Contributor

@Flamki I'm already working on this

@Flamki
Copy link

Flamki commented Jan 20, 2023

Yea you can carry on

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
bug
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Add updating Jenkins section in User's Handbook Vandit1604/jenkins.io
7 participants
@MarkEWaite @dduportal @krisstern @SahityaGupta25 @Vandit1604 @tanujdevops @Flamki