Improve Windows installation instructions

[mkoeppe]

We streamline the installation instructions for Windows by including conda-forge instructions.

Sage is stuck at version 9.5 in Ubuntu, the default Linux distribution on WSL, so this should not be our primary recommendation.

Preview: https://deploy-preview-37184--sagemath.netlify.app/html/en/installation/

Alternatives / follow-ups:

• Include a link to Microsoft Store search for Linux distros - https://www.microsoft.com/en-us/search/shop/apps?price=0&q=linux&devicetype=pc
• Include a link to Arch WSL in Microsoft Store - https://apps.microsoft.com/detail/9MZNMNKSM73X?hl=en-us&gl=US -- this is the only Linux distro in the Microsoft Store that has up-to-date SageMath packaging
• Include a link to "Import any Linux distribution to use with WSL" -- https://learn.microsoft.com/en-us/windows/wsl/use-custom-distro -- these instructions should work with any Docker image, so many options
• Create a WSL launcher app -- https://github.com/Microsoft/WSL-DistroLauncher, and document how users can "sideload" it -- https://learn.microsoft.com/en-us/windows/wsl/build-custom-distro#sideloading-a-custom-linux-distro-package
• Create a WSL launcher app and publish it to the Microsoft Store -- https://github.com/Microsoft/WSL-DistroLauncher?tab=readme-ov-file#publishing
• Cookiecutter for Sage user projects with devcontainer #34286
• Installation Guide: Document Sage installation on Windows via VS Code dev containers #37534

📝 Checklist

• The title is concise, informative, and self-explanatory.
• The description explains in detail what this PR is about.
• I have linked a relevant issue or discussion.
• I have created tests covering the changes.
• I have updated the documentation accordingly.

⌛ Dependencies

• Depends on Update Conda installation instructions to use Miniforge #37588 (merged here)

[tobiasdiez]

You said that the installation on Ubuntu is currently broken. Is this specific to WSL?

[mkoeppe]

You said that the installation on Ubuntu is currently broken. Is this specific to WSL?

What I wrote in the PR description was based on watching a student try it on his computer 2 weeks. I can't test it myself.

Just now I tested the sagemath package on the ubuntu:jammy Docker image. It installs and tests OK as of today.

In any case, the Ubuntu package is stuck at version 9.5, so for this reason alone it should not be our primary recommendation.

[tobiasdiez]

You said that the installation on Ubuntu is currently broken. Is this specific to WSL?

What I wrote in the PR description was based on watching a student try it on his computer 2 weeks. I can't test it myself.

Just now I tested the sagemath package on the ubuntu:jammy Docker image. It installs and tests OK as of today.

In any case, the Ubuntu package is stuck at version 9.5, so for this reason alone it should not be our primary recommendation.

Thanks for the details. But this argument (especially your last point) applies to plain ubuntu as well. So I would prefer to simply change the how to install on ubuntu section to give priority to conda, and then leave the wsl section untouched.

[mkoeppe]

change the how to install on ubuntu section to give priority to cond

We do not have such a section.

[tobiasdiez]

change the how to install on ubuntu section to give priority to cond

We do not have such a section.

Sorry, I meant the "linux" section.

[mkoeppe]

change the how to install on ubuntu section to give priority to cond

We do not have such a section.

Sorry, I meant the "linux" section.

That does not make much more sense either. The Linux section makes different recommendations based on the version of Sage that is found on the distribution.

The problem that I am solving here in this PR is that there are too many indirections, each of which can confuse our potential users. That's what "streamlining" means in the PR description.

[tobiasdiez]

change the how to install on ubuntu section to give priority to cond

We do not have such a section.

Sorry, I meant the "linux" section.

That does not make much more sense either. The Linux section makes different recommendations based on the version of Sage that is found on the distribution.

The same would then also apply to Windows, as it is possible to use many different linux distros via wsl (as we also say in the docs).

[mkoeppe]

This is not an interesting discussion.

[kcrisman]

Okay, let me see if I can summarize:

• Windows WSL has Ubuntu by default, and the very likely scenario on Windows is that people will not be using anything other than default.
• Apparently the Ubuntu version is stuck for some reason.
• Conda-forge (in some version) works
• So we should recommend this.

It will take me a little bit to test whether this actually works. But I do have access to a Windows computer if my son lets me on it 😄

However, I also don't want to get in the middle of the myriad meta-discussions going on around platforms etc. So I'm going to take the point of view that "Windows users probably need very explicit instructions, and shouldn't be asked to go to a scary Linux section" and not worry about Linux instructions, which however certainly might need updating as well.

Technical question: do we expect that once conda activate sage is done once, then sage will work (path etc.) from then on in? I know very little about conda.

[mkoeppe]

So I'm going to take the point of view that "Windows users probably need very explicit instructions, and shouldn't be asked to go to a scary Linux section" and not worry about Linux instructions, which however certainly might need updating as well.

Yes, that's also my viewpoint here. If not for anything else, then certainly for keeping the focus of the PR as narrow as possible. After all, even with this deliberately narrow focus, it has been sitting for 3 weeks.

Technical question: do we expect that once conda activate sage is done once, then sage will work (path etc.) from then on in? I know very little about conda.

No, conda activate only affects the current shell session. To persist it, one would need to add the command to a shell initialization file such as .bash_profile

[mkoeppe]

I'm setting it to blocker because it needs to make its way in the stable release.

[kcrisman]

I'll take a look once I get access to a Windows machine.

By the way, any sense on why the Ubuntu is stuck on such an old version? (Probably this was discussed ad nauseam elsewhere, sorry.)

[mkoeppe]

I think maintainer burnout + possibly a problem with brial (hence #36380)

[tobiasdiez]

Removing blocker as there are problems with other PRs, see #37428 for more details.

[mkoeppe]

I have merged #37588 (thanks @williamstein for testing that) and updated the instructions from there.

I'm setting back to "blocker" because this really should be merged in 10.3.

[mkoeppe]

@kcrisman With these changes merged, do you want to test again, or can we merge?

[jhpalmieri]

I'm posting to record a vote of -1 on behalf of Tobias Diez.

[jhpalmieri]

Tobias added the "disputed" label and has requested that it be removed, so I am doing so. Also, based on the policy stated at https://groups.google.com/g/sage-devel/c/XDvKkMRoDk4/m/0yrtdKkGAwAJ, "if there is disagreement about whether a PR should be marked as a blocker, mark it as critical instead." So I am marking this as critical.

[mkoeppe]

How can there be a vote if the PR is not "disputed" any more?

[jhpalmieri]

In my opinion, if it's not disputed, "-1" votes have no clear impact, other than to let developers know that someone has some objections.

[kcrisman]

@kcrisman With these changes merged, do you want to test again, or can we merge?

Ideally someone should test again, though William's other testing is good. I just worry about Windows being wonky. However, I do vote +1 for this change overall, to be clear.

---

Comments on testing:

• It does ask a few questions in the install process for miniforge, so one might want to note that in the instructions (specifically when running the bash script), since Windows users may not be used to text license questions and typing "yes" 😄
• Still no one has answered my question about whether the Python 3.11 is brittle. How often will that have to be updated? Is there a version-agnostic way to do that?
• Even with an existing mambaforge, it worked fine installing Sage with miniforge instead, it was "smart enough" to ask questions. So the actual instructions are fine, and 2+2=4.
• Finally, I think the user should be notified in these instructions (again, thinking of absolute newbies) that sage -n will give a notebook, but they may have to copy and paste the link given in the command line. I don't know if that belongs in one of these files (maybe after "You can now start SageMath as follows:"), but I think it's important. (Until a "WSL launcher app" shows up, that would be cool too!)

---

Addressing the issue implicitly raised, this comment suggests that, while Tobias is currently voting -1 due to duplication, it might just as easily be possible to have a quick followup PR that then uses some standard rst tool to remove that duplication. I don't really care if it happens here or there, but it does seem helpful in terms of preventing doc rot.

[mkoeppe]

• no one has answered my question about whether the Python 3.11 is brittle. How often will that have to be updated? Is there a version-agnostic way to do that?

Sorry for missing this.
That it is written there explicitly -- instead of referring the reader to go elsewhere to look for this information -- is to serve the reader.

Keeping the documentation source a simple .rst file (instead of generating it somehow from some template file so that we could refer to a variable) -- this is to keep the structure of our documentation sources as simple and straightforward as possible -- this serves the contributors to the documentation.

The cost of this (= the cost of updating this occurrence) is low, as the update happens only about once a year, and the places to change are easy to find, in particular for those who know how to make the updates of the supported Python versions.

[mkoeppe]

Tobias is currently voting -1 due to duplication

FWIW, I recommend not to take such rationalizations at face value.

[kcrisman]

Sorry for missing this.

No problem.

The cost of this (= the cost of updating this occurrence) is low, as the update happens only about once a year, and the places to change are easy to find, in particular for those who know how to make the updates of the supported Python versions.Message ID: ***@***.***>

Okay, I guess we do have to search for that every so often ...

[kcrisman]

Tobias is currently voting -1 due to duplication FWIW, I recommend not to take such rationalizations at face value.

Thankfully, I have the margin to do so, though I understand why others might not.

…

Message ID: ***@***.***>

[mkoeppe]

• It does ask a few questions in the install process for miniforge, so one might want to note that in the instructions (specifically when running the bash script), since Windows users may not be used to text license questions and typing "yes"

Done in d3a2a16

[mkoeppe]

• I think the user should be notified in these instructions (again, thinking of absolute newbies) that sage -n will give a notebook, but they may have to copy and paste the link given in the command line. I don't know if that belongs in one of these files (maybe after "You can now start SageMath as follows:"), but I think it's important.

Done in 4eacb7b, please take a look.

[github-actions]

Documentation preview for this PR (built with commit 4eacb7b; changes) is ready! 🎉

[kcrisman]

Thanks for addressing all these concerns. While I still hope for an nth iteration of a double click installer, this is fairly painless as such things go in our Windows ecosystem experience.

[mkoeppe]

@kcrisman Thanks for the review!

[mkoeppe]

@vbraun Please merge. Can't set to blocker because policy.