Overhaul "Install" instructions #48

avivace · 2023-07-02T10:59:59Z

I wasn't quick enough to review #47, so let me try again.

The install page suffers from a lot of problems right now, making the whole thing unreadable and inaccessible to the average target of "new users of RGBDS".

Let's try to review the criteria:

Keep the details to the minimum. We are not interesting on explaining the intricacies of installing on Windows or in which way different ways of installing on Windows are related.
Our primary dev environment (and the largest RGBDS user quota) target is "Linux". We have pre-built binaries for amd64 on the CI (?). Until we start packaging it for main distributions, that should be the primary suggested way to obtain the binaries. End of the story.
Reading the install page is incredibly complex right now and leads to so many choices that it makes me want to give up just looking at all the branches and choices I have to make.

Feel free to discuss any of these points. In the meantime, I started an overhaul:

Removed mention of rgbds2 package. Why would someone be interested in it? It will just make the explanation and the options more complex for new users. If I need an old version, I'll look up for an old release, no need to imply 3 choices in the Arch Linux tab. it's not an alternative/LTS branch receiving updates, so it's not like I need to subscribe to a rgbds2 package.
Made a generic "Linux" tab as the default. Go to releases, pick a pre-built binary for the arch you need. You're done.

Fixes #51.

ISSOtm · 2023-07-02T13:19:42Z

Are you sure the largest portion of our user base is on Linux? Lacking any better info (people will get mad if we add any telemetry), I've been referencing the Sublime Text extension's stats, which are approximately 50% Windows, 25% macOS, 25% Linux.
[EDIT] Since Sublime is non-free software, and not in any distro's default repos, maybe the Linux share is biased downwards. IDRK.

As far as I'm aware, distributing raw Linux binaries is a bad idea because they'll be incompatible across distributions? I will look up info on that.

avivace · 2023-07-20T10:40:48Z

Let's also remember to mention rgbenv

avivace · 2023-08-27T22:18:27Z

This is currently blocked by gbdev/rgbds#1148 not being applied to old releases, so we don't have the Linux build until we release

avivace · 2023-09-14T15:33:07Z

#51 could also be fixed here

ISSOtm · 2023-09-15T13:16:09Z

I'm not sure Docker would be much use for installing RGBDS?

src/pages/install/index.md

ISSOtm · 2023-09-15T13:36:17Z

src/pages/install/index.md


-:::
+The install instructions change a bit depending on the environment you wish to use RGBDS with.

 <details>
 <summary>"Plain" Windows (CMD, PowerShell)</summary>


Actually, the WSL instructions should instruct to refer to the Linux instructions for the corresponding Linux distribution (noting that if you don't know, it's probably Ubuntu).

I'm thinking we should organise the tabs something like WSL, then MSYS2 or Cygwin, and finally none of these. That should make what the last one is about, clearer. I think.

This seems a good idea, although I have no experience whatsoever on Windows so if you have any specific ideas on how to reorganize the Windows tab feel free to push

I'm not a Windows user anymore, but I think I have some ideas. I'll do that then.

src/pages/install/index.md

pinobatch · 2023-09-27T21:58:22Z

It has been suggested to use https://nightly.link/ to solve the lack of guest downloads for master.

avivace · 2023-09-27T22:05:07Z

@ISSOtm

I'm not sure Docker would be much use for installing RGBDS?

The container image provides a very quick way, literally a oneliner (if you have a container runtime installer ofc) to obtain a linux environment able to run AND build RGBDS (the version you're checking out, but potentially any other).

It may also be useful as a "base" image for pipelines.

Anyway, we'll have some stats in a while on how popular/really used really is, so I'm okay in removing it from the options if it we understand is not really used..

Another thing, are we really sure we want the Tabs navigation here? Now the instructions were slimmed down, they seem to amount just 4-5 lines per platform so I'm now sure if requiring additional clicks is really useful?

@pinobatch where should the nightly link https://nightly.link/gbdev/rgbds/workflows/testing/master go? In the "Install master?" (https://rgbds.gbdev.io/install/master) (which could also be renamed to "Canary" tbf, it's clearer

ISSOtm · 2023-09-28T12:23:17Z

src/pages/install/index.md

+Below is a list of Operative Systems for which pre-built executables are available. If none of these options fits your needs, you can [build from source](/install/source).



Suggested change

Below is a list of Operative Systems for which pre-built executables are available. If none of these options fits your needs, you can [build from source](/install/source).

Below is a list of OSes for which pre-built executables are available.

If none of these options fits your needs, you can [build from source](/install/source).

We can use <abbr title="Operating Systems"> to explain "OSes" instead, if desired.

ISSOtm · 2023-09-28T12:25:36Z

src/pages/install/index.md

-The install instructions change a bit depending on the environment you wish to use RGBDS with.
+Linux x86_64 ready binaries are available in our [Releases](https://github.com/gbdev/rgbds/releases) page.
+
+##### Arch


Suggested change

##### Arch

### Arch

We're only at heading level 2 here; but level 3 seems appropriate too.

ISSOtm · 2023-09-28T12:27:58Z

src/pages/install/index.md

+```bash
+pacman -S rgbds
+```
+


Suggested change

ISSOtm · 2023-09-28T12:28:27Z

src/pages/install/index.md


-:::
+The install instructions change a bit depending on the environment you wish to use RGBDS with.

 <details>
 <summary>"Plain" Windows (CMD, PowerShell)</summary>


I'm not a Windows user anymore, but I think I have some ideas. I'll do that then.

ISSOtm mentioned this pull request Jul 3, 2023

Create statically-linked Linux binaries on release gbdev/rgbds#1148

Merged

avivace mentioned this pull request Aug 25, 2023

Finding a Windows build of master is confusing #49

Closed

ISSOtm requested changes Sep 15, 2023

View reviewed changes

avivace marked this pull request as draft September 19, 2023 20:21

avivace added 2 commits September 24, 2023 21:31

Remove windows "tip"

16e1bfa

Remove mention of rgbds2

5ea3211

avivace force-pushed the install-overhaul-fixes branch from 9f87a70 to 5ea3211 Compare September 24, 2023 19:31

avivace changed the title ~~Improve Install documentation~~ Overhaul "Install" instructions Sep 25, 2023

avivace assigned avivace and ISSOtm Sep 25, 2023

avivace added documentation Improvements or additions to documentation enhancement New feature or request labels Sep 25, 2023

simplify instructions

1a98d37

avivace marked this pull request as ready for review September 25, 2023 23:10

avivace requested a review from ISSOtm September 25, 2023 23:10

ISSOtm requested changes Sep 28, 2023

View reviewed changes

ISSOtm and others added 2 commits September 28, 2023 22:29

Restructure and improve Windows install instructions

7f9500f

final formatting fixes

35e2a0d

avivace merged commit 89cdda3 into master Oct 11, 2023

avivace deleted the install-overhaul-fixes branch October 31, 2023 18:49

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Overhaul "Install" instructions #48

Overhaul "Install" instructions #48

avivace commented Jul 2, 2023 •

edited

Loading

ISSOtm commented Jul 2, 2023 •

edited

Loading

avivace commented Jul 20, 2023

avivace commented Aug 27, 2023

avivace commented Sep 14, 2023

ISSOtm commented Sep 15, 2023

ISSOtm Sep 15, 2023

avivace Sep 27, 2023

ISSOtm Sep 28, 2023

ISSOtm Sep 28, 2023

pinobatch commented Sep 27, 2023

avivace commented Sep 27, 2023

ISSOtm Sep 28, 2023 •

edited

Loading

avivace Oct 11, 2023

ISSOtm Sep 28, 2023 •

edited

Loading

ISSOtm Sep 28, 2023

ISSOtm Sep 28, 2023

		Below is a list of Operative Systems for which pre-built executables are available. If none of these options fits your needs, you can [build from source](/install/source).

	Below is a list of Operative Systems for which pre-built executables are available. If none of these options fits your needs, you can [build from source](/install/source).
	Below is a list of OSes for which pre-built executables are available.
	If none of these options fits your needs, you can [build from source](/install/source).

Overhaul "Install" instructions #48

Overhaul "Install" instructions #48

Conversation

avivace commented Jul 2, 2023 • edited Loading

ISSOtm commented Jul 2, 2023 • edited Loading

avivace commented Jul 20, 2023

avivace commented Aug 27, 2023

avivace commented Sep 14, 2023

ISSOtm commented Sep 15, 2023

ISSOtm Sep 15, 2023

Choose a reason for hiding this comment

avivace Sep 27, 2023

Choose a reason for hiding this comment

ISSOtm Sep 28, 2023

Choose a reason for hiding this comment

ISSOtm Sep 28, 2023

Choose a reason for hiding this comment

pinobatch commented Sep 27, 2023

avivace commented Sep 27, 2023

ISSOtm Sep 28, 2023 • edited Loading

Choose a reason for hiding this comment

avivace Oct 11, 2023

Choose a reason for hiding this comment

ISSOtm Sep 28, 2023 • edited Loading

Choose a reason for hiding this comment

ISSOtm Sep 28, 2023

Choose a reason for hiding this comment

ISSOtm Sep 28, 2023

Choose a reason for hiding this comment

avivace commented Jul 2, 2023 •

edited

Loading

ISSOtm commented Jul 2, 2023 •

edited

Loading

ISSOtm Sep 28, 2023 •

edited

Loading

ISSOtm Sep 28, 2023 •

edited

Loading