search

ScoopInstaller / scoopinstaller.github.io

ScoopInstaller homepage and search engine
https://scoop.sh
MIT License
77 stars 19 forks source link

Initial steps for merging upstream #10

Closed rashil2000 closed 2 years ago

rashil2000 commented 2 years ago

Hi!

So according to the recent poll, looks like most people favour ScoopSearch. Which is awesome!

The user-facing website looks like this: ({base} is scoopsearch.github.io as of now)

So the first step would be to create a brand new homepage (the current one has some slightly out-of-date info, but we can start from scratch). The broad overview can be taken from the current Readme, selecting the most relevant parts - i.e. what Scoop is, why you need it, and a quick-start. Links for documentation (the Scoop GitHub Readme and Wiki) can be added at the bottom.

Let me know what you think!

rashil2000 commented 2 years ago

I've done some React before, I'm willing to take a shot at this.

gpailler commented 2 years ago

Hey @rashil2000,

I'm really pleased that you want to help on that! I can add you as a contributor to the project so you can work on it directly. Does it work for you?

Please just pay attention that I'm currently refactoring the codebase to switch from class components to function components + hooks. It should be completed quite soon.

rashil2000 commented 2 years ago

I'm really pleased that you want to help on that! I can add you as a contributor to the project so you can work on it directly. Does it work for you?

Definitely!

Please just pay attention that I'm currently refactoring the codebase to switch from class components to function components + hooks. It should be completed quite soon.

Sure, no worries. I can wait :)

rashil2000 commented 2 years ago

Something to add (for later): we don't necessarily need to use a different repo for the hosting the build files, right? The code can live on master branch while the build files can be served on gh-pages branch (when we transfer the repo to the ScoopInstaller org - i.e. github.com/ScoopInstaller/ScoopInstaller.github.io).

gpailler commented 2 years ago

Hey @rashil2000, I sent you an invite to be part of the ScoopSearch organization + you should have access to ScoopSearch.WebSearchEngine.

You can take a look on the develop branch. It contains my latest changes (not published on scoopsearch.github.io yet). This develop branch is build and served on https://scoopsearch.github.io/scoopsearch-dev.github.io/.

To run ScoopSearch.WebSearchEngine locally, you can use this dev key REACT_APP_AZURESEARCH_KEY = "78CB5DCD0A7ABACE5B4DC3C34BC54C8F" in your .env.local and start your local web server on port 3000 or 30000 (CORS origins http://localhost:3000 or http://localhost:30000 are allowed)

Something to add (for later): we don't necessarily need to use a different repo for the hosting the build files, right? The code can live on master branch while the build files can be served on gh-pages branch (when we transfer the repo to the ScoopInstaller org - i.e. github.com/ScoopInstaller/ScoopInstaller.github.io).

Yes sure, we can use a gh-pages branch to store and serve the build files. The dedicated repo was needed to serve the files from the organization url directly (https://scoopsearch.github.io) but for Scoop, we'll have a custom domain so it should not be an issue.

rashil2000 commented 2 years ago

Hey @rashil2000, I sent you an invite to be part of the ScoopSearch organization + you should have access to ScoopSearch.WebSearchEngine.

Thanks, accepted!

You can take a look on the develop branch. It contains my latest changes (not published on scoopsearch.github.io yet). This develop branch is build and served on https://scoopsearch.github.io/scoopsearch-dev.github.io/.

Looks great to me!

To run ScoopSearch.WebSearchEngine locally, you can use this dev key REACT_APP_AZURESEARCH_KEY = "78CB5DCD0A7ABACE5B4DC3C34BC54C8F" in your .env.local and start your local web server on port 3000 or 30000 (CORS origins http://localhost:3000 or http://localhost:30000 are allowed)

Sure, will do.

gpailler commented 2 years ago

Welcome on board 👍

gpailler commented 2 years ago

Hey @JanPokorny, Could you give us your feedback about the new homepage https://scoopsearch.github.io/scoopsearch-dev.github.io/. Do you see any improvement in the layout?

Thanks!

rashil2000 commented 2 years ago

The side-by-side layout for code and summary was partly inspired by https://brew.sh - I feel this is important to mention 😅

JanPokorny commented 2 years ago

@gpailler Thanks for tagging me, I'll look into it later today!

JanPokorny commented 2 years ago

@gpailler First of all, it looks very good! I see the Brew inspiration but that's cool since the Brew website is pretty nice (apart from questionable font sizing 😃 )

Second of all, here's the wall of text you were expecting:

scoop install python ... 'python' (3.10.4) was installed successfully!

python -c "print('Hello from Python installed by Scoop!')" Hello from Python installed by Scoop!

Scoop installs all packages in a portable way, keeping them neatly isolated in the ~/scoop folder. Binaries available on PATH are managed using "shims", a kind of command-line shortcuts. This way, packages are always cleanly uninstalled and you can be sure what tools are currently in your PATH. You can even switch on the fly to what tool the shims point, without reinstalling them!

python --version Python 2.7.18

scoop reset python ...

python --version Python 3.10.4

> scoop bucket add games
...
The games bucket was added successfully.

> scoop search ttd
'games' bucket:
    openttd (1.10.0)
rashil2000 commented 2 years ago

I'd start with mentioning that my goal for the homepage was to make it as minimal as possible, while still providing enough details to just get started. This is in line with the old homepage (except that instead of the youtube video, I put in a couple of code examples). I'll try to respond to each of the feedback points.

  • Place a logo before the "Scoop" heading, or at least an ice-cream emoji 🍨 (it's already in the favicon)

Will do.

  • Nice to have/silly idea: A text field/widget that has the text > scoop install something where "something" is animated -- periodically deleted and retyped as if user was typing, showing an assorted selection of tools one might want to install through scoop -- this draws attention and quickly shows what scoop does. (I've seen some corporate websites use this kind of animation, seems pretty suited here) -- similar to the result of this snippet https://stackoverflow.com/a/32496921/6099426

Great idea, but I'd keep this as a low priority item for now. (I'm also not sure where this would go, exactly).

  • There is no search bar on the homepage like Brew has, and IMO you should totally copy that too -- it adds discoverability, user can immediately learn what is installable. In the current state, the search functionality is very hidden!

IMO we should not do this. We would face problems here, like how will the results be shown? In a dropdown (which will give us very less space to show the details) or normally (which will push down the content on the homepage). I think the dedicated search page for apps is good, we should avoid duplication.

  • PowerShell 5.1 is pre-installed on all currently suppored Windows versions, no need to tell user to ensure version

It's not on Windows 7 😉. We still support it.

  • Tell them how to open PowerShell (search in Start for "powershell" seems easiest)
  • Spell out the command Set-ExecutionPolicy RemoteSigned -scope CurrentUser and specify to "press A"

IMO this bit of hand-holding might not be necessary. If someone is installing a CLI package manager, they definitely know how to open a terminal 😅

  • In the installation example, the full scoop output is not really relevant, I'd rather use the space to install a CLI tool and then how one can use it immediately, like this:
> scoop search python
'main' bucket:
    python (3.10.4)
    winpython (3.8.9.0)

> scoop install python
...
'python' (3.10.4) was installed successfully!

> python -c "print('Hello from Python installed by Scoop!')"
Hello from Python installed by Scoop!

Seems good, will do.

  • I'd extend the next section a bit.

Scoop installs all packages in a portable way, keeping them neatly isolated in the ~/scoop folder. Binaries available on PATH are managed using "shims", a kind of command-line shortcuts. This way, packages are always cleanly uninstalled and you can be sure what tools are currently in your PATH. You can even switch on the fly to what tool the shims point, without reinstalling them!

  • The code example with dir ~\scoop doesn't say much about what Scoop does. I'd replace it with this one, demonstrating how shims work:
> scoop install python27
...
'python' (2.7.18) was installed successfully!

> python --version
Python 2.7.18

> scoop reset python
...

> python --version
Python 3.10.4

Actually, the entire infra around managing shims was refactored recently. See https://github.com/ScoopInstaller/Scoop/pull/4727 and https://github.com/ScoopInstaller/Scoop/pull/4736 for more details. The old method of switching apps was cumbersome and unintuitive, and is no longer recommended.

  • The section "Discovering Packages" could use a code example too:
> scoop bucket add games
...
The games bucket was added successfully.

> scoop search ttd
'games' bucket:
    openttd (1.10.0)

Will do.

  • I'd add a simple footer (with licence, github link and other standard stuff)

This should be done for all three pages, so I think @gpailler would be better suited for this particular task,

JanPokorny commented 2 years ago

@rashil2000

regarding search: My idea was placing a dummy search box that would move the user to the "Search" tab once anything was typed in, or perhaps even once it's focused. Since the whole website is a SPA, the tab transitions are instant, so this is IMO very doable.

regarding PowerShell 5.1: Alright then, in that case I'd add a note that if you're on Windows 7, you have to install it, and provide a link.

regarding the "hand-holdy" instructions: You'd be surprised. There are people that use Windows for programming but never touched PowerShell, only cmd, and even ones that only ever use WSL but still need to install some Windows-side tools. There are even people who don't program at all but still use Scoop, for example to install and update GOG Galaxy integrations. I have personally helped guide a civil engineering student over the phone to install Scoop and some stuff using it since they needed to use an application that required a specific Python version and some other tools to be in PATH to run properly, and Scoop was the easiest way. IMO there is no harm in being a bit more specific/inclusive here!

gpailler commented 2 years ago

Thanks @JanPokorny for your feedback and thanks @rashil2000 for the follow up ;-)

regarding search: My idea was placing a dummy search box that would move the user to the "Search" tab once anything was typed in, or perhaps even once it's focused. Since the whole website is a SPA, the tab transitions are instant, so this is IMO very doable.

Yep, I also think that we should have a search textfield on top of the homepage. The search is the most important feature as you install Scoop once but search for apps all the time so it should be immediately available from the homepage.

  • Tell them how to open PowerShell (search in Start for "powershell" seems easiest)
  • Spell out the command Set-ExecutionPolicy RemoteSigned -scope CurrentUser and specify to "press A"

IMO this bit of hand-holding might not be necessary. If someone is installing a CLI package manager, they definitely know how to open a terminal 😅

I'm not sure we should explain HOW to open a PowerShell terminal but we can change the wording to explain that the user HAS to open a PowerShell terminal to run the installation command. About Set-ExecutionPolicy, I never remember the syntax and always have to ask Google so it could be useful to have the whole line displayed 😅.

It could be something like:

Open a PowerShell terminal (>= 5.1 or PowerShell Core) and run:
> Set-ExecutionPolicy RemoteSigned -scope CurrentUser # Optional: Needed to run remote script the first time
> Invoke-WebRequest get.scoop.sh | Invoke-Expression

or

Open a PowerShell terminal (>= 5.1 or PowerShell Core) and run:
> Invoke-WebRequest get.scoop.sh | Invoke-Expression
(you may have to run `> Set-ExecutionPolicy RemoteSigned -scope CurrentUser` first if you never used a remote script before)

I'd add a simple footer (with licence, github link and other standard stuff) Will do!

rashil2000 commented 2 years ago

Yep, I also think that we should have a search textfield on top of the homepage. The search is the most important feature as you install Scoop once but search for apps all the time so it should be immediately available from the homepage.

If the search box redirects to the /apps page as soon as it gets input or focus, then I agree it's a good idea, we can implement it.

gpailler commented 2 years ago

Here is a list of the current tasks to follow up on this topic.

I think we are good to deploy the new version with the textfield and the updated wording. The animation can be handled separately. @rashil2000 are you handling one (or all 😄 ) of the remaining tasks?

Thanks

rashil2000 commented 2 years ago

Hi!

Sorry for the delay, I had my endsem exams so I got busy 😅

I think the search text field part might be a bit complicated for me. I'll handle the updated wording part as soon as I can.

For the animation part, we can visit it at a later time.

gpailler commented 2 years ago

Hi @rashil2000 . Hope your exams went well 🤞 I'll take a look on the search text field then.

Thanks!

JanPokorny commented 2 years ago

For the animated example, I have came across a page that uses this effect, so dropping it here for reference: https://www.localsolver.com/

gpailler commented 2 years ago

For the animated example, I have came across a page that uses this effect, so dropping it here for reference: https://www.localsolver.com/

Thanks for the reference! I found react-code-auto-typing that could probably do the job

gpailler commented 2 years ago

I just added the search text field on top of the homepage. When you validate the text field, you are redirected to the /apps page with the search results.

rashil2000 commented 2 years ago

Looks awesome!

rashil2000 commented 2 years ago

Would it be possible/would it be a good idea to redirect as soon as text is input (i.e. search as you type)?

gpailler commented 2 years ago

Would it be possible/would it be a good idea to redirect as soon as text is input (i.e. search as you type)?

Great idea. I applied the change and it works fine 👍 What are your thoughts?

rashil2000 commented 2 years ago

Yup, works as expected!

Meanwhile I have pushed a commit to update the wording.

JanPokorny commented 2 years ago

Open a PowerShell terminal (version 5.1 or later) by searching in the Start menu.

Meh, this still sounds kinda weird.

What about using <abbr> to hide the lecture? https://jsbin.com/qororawuba/edit?html,output It's not commonly used nowadays because mobile devices don't support it well, but that's not really the target demographic...

rashil2000 commented 2 years ago

How is it weird? It says exactly what the user should do, regardless of their technical expertise

JanPokorny commented 2 years ago

IMO:

Hiding the extra instructions (for those who wonder/are unsure) in the <abbr> while keeping the actual text short seems good to me, what do you think? Check the link for mockup (GitHub does not support abbr in comments....) https://jsbin.com/qororawuba/edit?html,output

rashil2000 commented 2 years ago

Added https://github.com/ScoopSearch/ScoopSearch.WebSearchEngine/commit/91ebd3ad095d2fbb485c997f35b80a1937c54078

rashil2000 commented 2 years ago

@gpailler I think we can deploy the current set of changes to main branch. This will allow us to close the 3 currently open issues. I'll open a new one for auto-typing effect and label it as 'good-first-issue' to encourage new contributors.

Then we can plan and move ahead with repository transfer and DNS mapping changes.

gpailler commented 2 years ago

Great. Thanks for your hard work and your feedback! Let's merge to main and deploy

gpailler commented 2 years ago

We are live https://scoopsearch.github.io/ 🚀 🎉

JanPokorny commented 2 years ago

I must say -- I love it! Great job.

rashil2000 commented 2 years ago

Awesome.

For repository transfer, we should do something like this:

I don't have the required rights for repo transfers to ScoopInstaller org, so I'll tag the people who do - @gpailler @rasa @niheaven and @issaclin32

Once the transfer is done and all code is updated to point to new URLs (Azure deployments, repo links, workflows etc.), I'll ask @ lukesampson to finally update the DNS mapping to point scoop.sh to scoopinstaller.github.io.

issaclin32 commented 2 years ago

I am not familiar with the transfer process, but looks like an easier way to do it is to add me to ScoopSearch as an Admin, then, let me transfer the repos to ScoopInstaller. Github docs

rashil2000 commented 2 years ago

As admin of the current ScoopSearch org, @gpailler will have to initiate the transfers. Then, any admins of ScoopInstaller org can 'accept' the transfer to complete the process.

gpailler commented 2 years ago

I'm not familiar with the transfer process either but it looks quite straight-forward.

  1. @gpailler gives admin permission to @issaclin32 on all the ScoopSearch repositories
  2. @issaclin32 starts by transferring ScoopSearch/ScoopSearch-dev.github.io to ScoopInstaller/ScoopInstaller-dev.github.io
  3. @gpailler updates ScoopInstaller/ScoopInstaller-dev.github.io settings
    • Add a deploy key (Settings -> Deploy key)
    • Publish on https://scoopinstaller.github.io/scoopinstaller-dev.github.io (Settings -> Pages)
  4. We validate that everything is working (repository transfer / GitHub Pages / CORS)
  5. @issaclin32 transfers:
    • ScoopSearch/ScoopSearch.WebSearchEngine to ScoopInstaller/ScoopInstaller.github.io
    • ScoopSearch/ScoopSearch.AzureFunctions to ScoopInstaller/ScoopInstaller.AzureFunctions You can choose different names in the ScoopInstaller organization. The only requirement is a ScoopInstaller.github.io repo to publish the site, either a dedicated repo, either using a gh-pages branch. On my side, I would prefer ScoopInstaller/Website, ScoopInstaller/Website.AzureFunctions and ScoopInstaller/ScoopInstaller.github.io but up to you for the names.
  6. @gpailler updates the transferred repos:
    • Add a deploy key on ScoopInstaller.github.io (Settings -> Deploy key)
    • Add secrets on ScoopInstaller.AzureFunctions (Settings -> Secrets -> Actions):
      • AZURESEARCHADMINAPIKEY
      • AZURE_FUNCTIONAPP_PUBLISH_PROFILE
      • GITHUBTOKEN
    • Add secrets on ScoopInstaller.github.io (Settings -> Secrets -> Actions):
      • GHPAGES_DEPLOY_KEY
      • GHPAGES_DEPLOY_KEY_DEV
      • REACT_APP_AZURESEARCH_KEY
    • Update codebase:
      • In ScoopInstaller.github.io => .env, deploy.yml, Footer.tsx
      • In ScoopInstaller.AzureFunctions => function-app.yml
    • Run the GitHub actions and checks that everything is properly deployed
    • Update ScoopInstaller/ScoopInstaller.github.io settings to publish on https://scoopinstaller.github.io (Settings -> Pages)
  7. @gpailler adds a redirection from https://scoopsearch.github.io to https://scoopinstaller.github.io

Does it work for you?

issaclin32 commented 2 years ago
  1. @issaclin32 starts by transferring ScoopSearch/ScoopSearch-dev.github.io to ScoopInstaller/ScoopInstaller-dev.github.io

Done.

gpailler commented 2 years ago

@issaclin32 Thanks 👍. Could you rename ScoopSearch-dev.github.io to ScoopInstaller-dev.github.io and give me admin permission on this repo for 3. ?

issaclin32 commented 2 years ago

@issaclin32 Thanks 👍. Could you rename ScoopSearch-dev.github.io to ScoopInstaller-dev.github.io and give me admin permission on this repo for 3. ?

Done. Sorry that I forgot to check the repo name.

gpailler commented 2 years ago

Dev site is properly deployed on https://scoopinstaller.github.io/scoopinstaller-dev.github.io/ 🎉

It was easier that I thought as the deploy key was transferred alongside the repo and the site was automatically published. I just had to rebuild the site to use the new public URL.

Next step is 5. for @issaclin32

issaclin32 commented 2 years ago

Next step is 5. for @issaclin32

  • If you decide to transfer ScoopSearch/ScoopSearch.WebSearchEngine to ScoopInstaller/scoopinstaller.github.io, then I will deploy the production website on a gh-pages branch.
  • If you decide to use a dedicated repo for ScoopSearch.WebSearchEngine (like Website), then I will need an empty scoopinstaller.github.io repo so I can deploy the site.

Done. I chose the first option. That is, transferring ScoopSearch/ScoopSearch.WebSearchEngine to ScoopInstaller/scoopinstaller.github.io, and deploy the website on gh-pages.

gpailler commented 2 years ago

We are all good! https://scoopinstaller.github.io/ is up and running! 🚀

(I added a redirection on https://scoopsearch.github.io/ to the new website and I will apply some renaming in ScoopInstaller.AzureFunctions later on, but it's not required for now)

rashil2000 commented 2 years ago

Great!!! 🥳🥳

All that's left now is to update the DNS mapping for scoop.sh, which will be done by @lukesampson...

gpailler commented 2 years ago

👍 I have updated the workflow to deploy on https://scoop.sh with the proper CNAME 53b1fb38b0b462fe0c9a4954d397001eb5757240

@lukesampson, I think that something is incorrect with the new DNS configuration. I see a CNAME record for www.scoop.sh, but no A records for scoop.sh. According to the documentation, I think that the A records should be added on scoop.sh.

$ dig www.scoop.sh @ns-1776.awsdns-30.co.uk +nostats +nocomments +nocmd
;www.scoop.sh.                  IN      A
www.scoop.sh.           3600    IN      CNAME   scoopinstaller.github.io.
scoop.sh.               172800  IN      NS      ns-1530.awsdns-63.org.
scoop.sh.               172800  IN      NS      ns-1776.awsdns-30.co.uk.
scoop.sh.               172800  IN      NS      ns-308.awsdns-38.com.
scoop.sh.               172800  IN      NS      ns-604.awsdns-11.net.

$ dig scoop.sh @ns-1776.awsdns-30.co.uk +noall +answer -t A
[nothing]
lukesampson commented 2 years ago

Oh interesting. There was a Route 53 alias for scoop.sh but I guess it didn't work. And Github told me that A records were "old" and I should use a CNAME. I've added the A records you suggested so hopefully that works. I think the TTL was 1 hour so hopefully the changes are visible soon.

gpailler commented 2 years ago

Thanks for the change. https://scoop.sh is live now 👍 I have ticked the Enforce HTTPS option. Does it work for you?

niheaven commented 2 years ago

So the next step is maintaining the help documents on the website, and the wiki pages under scoop core needs some reorganization.

JanPokorny commented 2 years ago

@niheaven Agreed. The shiny new website (I love it!) does a good job introducing what Scoop can do, but does not really explain how to use it. I see that the Using Scoop wiki section contains most of the info a first-timer would need to start utilizing Scoop (except maybe adding a new bucket -- most people would want at least extras, and adding a bucket involves installing git, otherwise it errors out, so it needs some explanation). IMO it's worth to extract this section to a separate page and link users to it as "Next steps" from the installation section on the website.

gpailler commented 2 years ago

Hi, Yep, it definitely makes sense to improve the website with some additional content. Could we create dedicated issues to track them separately? I really would like to close this one 😄