Open ucodery opened 2 months ago
It would be great if we could provide examples for native Windows users, as we do for POSIX users. We very occasionally reference command differences between command examples for those on Windows, but we don't every provide them as alternative top-level sample code.
We do IME try to craft commands in such a way they they will work unaltered on the most systems possible, but it is not always possible. The bash
examples, at least, need close scrutiny.
As a possible solution, we could adopt tabbed code callouts, using a library like https://sphinx-tabs.readthedocs.io/en/latest/ or https://pypi.org/project/sphinx-code-tabs/ (although using an extension directive could limit our ability to do other more advanced code examples like #239).
One thing to decide is which environment to target as the native Windows environment. I would say that all of WLS(2), git-bash, cygwin, mingw, msys2 can be skipped as our POSIX examples should already generally work there. That leaves either a cmd
or powershell
environment. Unfortunately, these two environments are not really interchangeable, and whichever one we support will leave the other in the cold.
Also, this is strongly related to #134
All excellent points! And good eye on noting the other issue re. general unfamiliarity with command line use.
Sounds like it is time for me to install hatch under Windows, and try out the various options. I had better not offer to do this until after Tax Day, though. 😁
Just FYI, I have not forgotten...just got swamped with other things.
oh no worries @ptressel i just spent some time today trying to wrap up issues and pr's and am behind as well ✨ i think the windows tabs idea is a great one. the challenge that i have personally is that i don't have a windows computer / vm here right now to test things on.
i have considered making a vm on my mac to test all things windows. i also don't have a good sense of what shells windows users prefer.
When i taught Python and bash we used to suggest that all windows users use gitbash as it was the most straight forward tool to download, install and use. however most of my students were new to shell / bash so they didn't have a preference. i don't know what to suggest here in terms of which shell to add a tab for.
@ptressel @ucodery do you have any suggestions? we literally ran into this in our workshop the other week. i agree 💯 that it's important!!
There are at least five options...listed here in likely preference order.
1) Commands adapted to run on the Windows command line (cmd) -- this is what's available with no work. 2) Git Bash -- the main issue is the path -- are bash commands masking items with the same name in the Windows path? -- and the home directory -- Git Bash defaults to the user's directory rather than Documents, which is probably the right choice, but may be a surprise. 3) PowerShell -- also available by default, but less commonly used than cmd. 4) Windows Subsystem for Linux (WSL) -- an installable tool from Microsoft that allows running a Linux distro on Windows. It's an impressive piece of work, as (if I understand correctly) it translates operations into native Windows calls -- it's not a VM. 5) Cygwin bash -- I don't know what the maintenance status is these days.
Windows users will have cmd, and may have used it. If they install git from git-scm.com, then they'll have Git Bash (IIRC). Those are likely the two best options. If we find out that the commands for use with Git Bash are identical to those for Linux, then asking folks to install git gets a big boost in preference, as there would be no need for separate Windows commands beyond some setup.
(I predate the command line -- started with FORTRAN coding sheets and punched cards. :D )
Just to add to what @ptressel already said
cmd
is probably the most "obvious" choice. It's the oldest and most consistently-available option. It's the sh
of Windows - always there, but full of old and strange conventions and not preferred (IME) by those with more technical knowledge. But then those technical users know what you are trying to convey and are likely to be able to translate to their preferred workflow.git bash
certainly was the preferred shell for dev examples in the past, but IME at least with software engineers WLS is much preferred these days. However, both use a true bash
and the commands we already have should work. If not, they should be changed to work on a Linux bash and WLS bash.powershell
is the only other native choice besides cmd
. It's new and fancy and has it superfans. If cmd
is Windows' sh
then powershell
is its fish
. As someone who helps maintain terminal installation commands for Windows software I can tell you that whichever you pick there will be users that copy the provided command and paste it into their preferred (or only know) terminal and get confused why the docs have a command that errors out. Not matter what warnings you place there.WSL
is great, very popular, but we don't need separate commands for it. Also IIRC some Windows editions won't support WSL.Cygwin
is still maintained and works just fine. I would avoid it for new users though. And once again, it is POSIX so no new commands if we did recommend it.my first pick would be WSL, for some reasons:
of course, mainly of my points are based on my experience, and of course, my point here is not about to use it as a preferred tool, but at least it would be nice to not ignore it. and additionally, it is really easy to configure and easy to use it.
I've found myself in the need of a python development environment for a beginner on Windows just some days ago. I feel like I can really recommend miniforge:
code
command launching vs code in the related conda/mamba environment, so one can use git extensions in vs code, rather than "bother" with command lines.@cmarmo i am a HUGE fan of miniforge but i never knew about the prompt that it offers. how do you invoke a miniforge prompt?
my quick read on WSL (i could be wrong y'all) is that it might be more involved to install / setup. can anyone confirm and or tell me my read is wrong!?
What if we consider a few options:
tell people about WSL in case they might be interested in a more robust solution? this one just sounds a bit more complex to me (again i could be wrong!)
@ptressel and @ucodery both have the cmd prompt first for windows users. we could include commands for that prompt (if they will consistently work) i'm just nervous about things consistently working across various versions of windows. btw i do remember using windows ages ago and the DOS prompt.
how do you invoke a miniforge prompt?
At least in the last version I've installed, the installer put it in the Windows Start menu, I looked for it with the search bar.... sorry I can't provide a screenshot, I don't have a Windows system on hand right now.
no worries - please do not apologize! that is helpful to know!!
About command line stuff... I was hesitating to bring this up, but... There are a fair number of folks using Windows. The commands may look a bit different if executed in cmd...but not always. A fair number of tools that come in from the *x world will use forward slashes in paths, or not understand a drive letter, or require their own special syntax for that. Others will take back slashes, but need them quoted. The best ones know what OS they're running on, and do "when in Rome...".
Windows users could install Git Bash. Or Windows Subsystem for Linux (WSL; which allows having an entire Linux distro under Windows). Or the classic Cygwin. Or adapt the commands for running directly on Windows. The easiest option is likely Git Bash. It's not entirely friction-free, however, as Git Bash's executable path may differ from the Windows path.
I've mostly ended up modifying commands so they work on cmd, except when the documentation strongly encourages use of Git Bash. Or when there's a canned development environment that can be run on a virtual machine. That's what we used to do for an open-source emergency management tool I used to work on, when we participated in hackathons. It could take the entire day to set up our environment, so instead, we prepared pre-configured virtual machine images.
The following has a good list of the options, one could just drop in a reference to this at the outset, wherever it says "we don't support Windows". :D :D :D
https://itsfoss.com/run-linux-commands-in-windows/
_Originally posted by @ptressel in https://github.com/pyOpenSci/python-package-guide/pull/224#discussion_r1560142709_