Improve readme #686

paugier · 2024-11-27T14:00:54Z

I try to reorganize the README so that users can more easily find the information they need to install Miniforge.

The result can be read here https://github.com/paugier/miniforge/tree/improve-readme

paugier · 2024-11-27T14:10:22Z

README.md

 "Create start menu shortcuts" and "Add Miniforge3 to my PATH environment variable". The latter is
 not selected by default due to potential conflicts with other software. Without Miniforge3 on the
 path, the most convenient way to use the installed software (such as commands `conda` and `mamba`)
 will be via the "Miniforge Prompt" installed to the start menu.

+If desired, the
+`C:\Users\myusername\miniforge3\condabin` folder may be added to the path environment variable


Note that for installation for all users, the path is of course different. It would be good to mention it.

paugier · 2024-11-29T12:34:12Z

Note that I don't think the failure for miniforge / Miniforge-pypy3-Linux-aarch64 has anything to do with this PR.

hmaarrfk

I know I've seen you around, so I know you have the best intentions.

But as is, this diff moves too many pieces around and is difficult for me to review.

Maybe somebody else can help review it, but I have limited bandwidth for this.

I want to in general move people away from this page since this isn't the right place to discuss "general conda problems".

hmaarrfk · 2024-12-07T14:58:14Z

README.md

-| macOS   | x86_64             | macOS >= 10.9    | [24.3.0-0](https://github.com/conda-forge/miniforge/releases/tag/24.3.0-0) |
-| Windows | x86_64             | Windows >= 7     | [24.9.2-0](https://github.com/conda-forge/miniforge/releases/tag/24.9.2-0) |
+| OS      | Architecture       | Minimum Version | Miniforge Version                                                          |
+| ------- | ------------------ | --------------- | -------------------------------------------------------------------------- |


why is any of this section getting touched. it is here for historical purposes. please revert.

hmaarrfk · 2024-12-07T14:59:05Z

README.md

-[Ubuntu for Raspberry PI](https://ubuntu.com/raspberry-pi).
-The versions listed as "System: 32-bit" are not compatible with the installers on this website.
-
-`(***)` Apple silicon builds are experimental and haven't had testing like the other platforms.


I don't understand why you've removed so many lines from the front and are now starting with a "detail"

hmaarrfk · 2024-12-07T15:01:06Z

README.md


-Download the installer using curl or wget or your favorite program and run the script.
-For eg:
+If Miniforge is on the system path (default on macOS and Linux), its versions of the


I want to change the whole idea of "Miniforge" being on the path.

"Miniforge" gets "conda" and "mamba" on your system. Once it is installed, its "job" is done. I want to help emphasize this.

paugier · 2024-12-10T15:46:00Z

I know I've seen you around, so I know you have the best intentions.

My goal is to improve this README which is a real issue since I saw that many users get lost and do not manage to use the installer correctly.

I don't care about this PR. It might be bad. However, I'm sure that this file has to be deeply reorganized so that people with a limited experience in conda-forge should be able in 2 minutes to install miniforge correctly and get conda/mamba in their terminals.

But as is, this diff moves too many pieces around and is difficult for me to review.

This PR moves and reorganizes texts and Github is not very good are showing such changes.

One should really compare

before : https://github.com/conda-forge/miniforge
after : https://github.com/paugier/miniforge/tree/improve-readme

and think about the user experience of a user with no strong knowledge on conda, conda-forge, Github releases pages and co.

I want to in general move people away from this page since this isn't the right place to discuss "general conda problems".

Then what would be the right page for people wanting to install and setup conda/mamba with miniforge?

hmaarrfk · 2024-12-10T16:00:18Z

One should really compare

This helps alot. thanks I didn't think of that.

install and setup conda/mamba with miniforge?

"Install" is one thing. This is the right place for this. "The bash script Miniforge.sh crashed" should be addressed here.

"Setup" is a different thing that starts to emcompass the old .condarc file. I don't know where a good place for this is.

For example, this user #690 has anaconda's channel (well a mirror of it) included so I'm not sure how to start helping.

I think we are using https://github.com/conda-forge/conda-forge.github.io as a "catchall repository". However in #602 i made the point that this repo had more stars.

hmaarrfk

Thank you I think this is a step in the right direction. Just a few comments I would like your thoughts on.

hmaarrfk · 2024-12-15T21:29:12Z

README.md

-rm -rf ${CONDA_BASE_ENVIRONMENT}
+## Install
+
+On all platforms, the installation should be finalized with commands like


i don't think this is true on unix.

You should instead explain what the defaults will do, and explain why you suggestion is important.

hmaarrfk · 2024-12-15T21:29:23Z

README.md

 "Create start menu shortcuts" and "Add Miniforge3 to my PATH environment variable". The latter is
 not selected by default due to potential conflicts with other software. Without Miniforge3 on the
 path, the most convenient way to use the installed software (such as commands `conda` and `mamba`)
 will be via the "Miniforge Prompt" installed to the start menu.

+If desired, the
+`C:\Users\myusername\miniforge3\condabin` folder may be added to the path environment variable


hmaarrfk · 2024-12-15T21:31:04Z

README.md

+bash Miniforge3-$(uname)-$(uname -m).sh
+```
+
+or for non-interactive install (call with `-h` to list the extra options):


Suggested change

or for non-interactive install (call with `-h` to list the extra options):

The interactive installation will prompt you to add initialize conda with your shell. This is typically with recommended workflow.

For non-interactive install (for example on a CI), the following command can be used (call with `-h` to list the extra options):

hmaarrfk · 2024-12-15T21:31:38Z

README.md

+```sh
+bash Miniforge3-$(uname)-$(uname -m).sh -b
+```
+


Suggested change

In non-interactive installations, the conda initialization commands will not be run by default.

hmaarrfk · 2024-12-15T21:33:14Z

README.md

+### macOS with Homebrew
+
+On macOS, you can install miniforge with [Homebrew](https://brew.sh/) by running
+
+```sh
+brew install miniforge
+```
+


I would rather remove this section. I'm happy to point to it, but I would rather omit the installation instructions and add a disclaimer that users should turn their issues to homebrew prior to asking us to do so.

paugier · 2024-12-19T11:23:37Z

Thanks for the review @hmaarrfk! I'm not a good English writer but I tried to add clear explanations in e7201d3.

Again, it is easier to see what it gives in https://github.com/paugier/miniforge/tree/improve-readme

paugier · 2024-12-19T11:25:49Z

Note for myself: once we converge on something good here, it would be good to add few lines in https://conda-forge.org/download/

paugier added 2 commits November 27, 2024 14:02

README: format and regularize

f811d9a

Reorganize README for better readability

bfeba23

paugier requested a review from a team as a code owner November 27, 2024 14:00

paugier commented Nov 27, 2024

View reviewed changes

hmaarrfk reviewed Dec 7, 2024

View reviewed changes

Blgwp21 approved these changes Dec 15, 2024

View reviewed changes

hmaarrfk reviewed Dec 15, 2024

View reviewed changes

Take into account @hmaarrfk's suggestions

e7201d3

paugier force-pushed the improve-readme branch from dc14e0c to e7201d3 Compare December 19, 2024 11:13

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve readme #686

Improve readme #686

paugier commented Nov 27, 2024 •

edited

Loading

paugier Nov 27, 2024

hmaarrfk Dec 15, 2024

paugier commented Nov 29, 2024

hmaarrfk left a comment

hmaarrfk Dec 7, 2024

hmaarrfk Dec 7, 2024

hmaarrfk Dec 7, 2024

paugier commented Dec 10, 2024

hmaarrfk commented Dec 10, 2024

hmaarrfk left a comment

hmaarrfk Dec 15, 2024

hmaarrfk Dec 15, 2024

hmaarrfk Dec 15, 2024

hmaarrfk Dec 15, 2024

hmaarrfk Dec 15, 2024

paugier commented Dec 19, 2024

paugier commented Dec 19, 2024

-or for non-interactive install (call with `-h` to list the extra options):
+The interactive installation will prompt you to add initialize conda with your shell. This is typically with recommended workflow.
+For non-interactive install (for example on a CI), the following command can be used (call with `-h` to list the extra options):



	In non-interactive installations, the conda initialization commands will not be run by default.

Improve readme #686

Are you sure you want to change the base?

Improve readme #686

Conversation

paugier commented Nov 27, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

paugier commented Nov 29, 2024

hmaarrfk left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

paugier commented Dec 10, 2024

hmaarrfk commented Dec 10, 2024

hmaarrfk left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

paugier commented Dec 19, 2024

paugier commented Dec 19, 2024

paugier commented Nov 27, 2024 •

edited

Loading