Proposal for Local Windows Guides & Overall Local Guide Structure

[perappu]

Included in this PR:

• Combining local setup and dev setup
• Section for "alternative" setups from the main local setup guides
• A guide for setting up XAMPP on Windows
• A guide for setting up SSH on Windows (as well as empty sections for Mac and Linux)

This is an adapted version of the local setup guide on my personal blog.

Some rationale for my changes:

• I propose combining together the concepts of a "local setup" and "dev setup".
  Given that our target audience has little to no experience with software development, I believe it's valuable to simultaneously explain the why to what we're doing. It does end up with a lengthier guide, but I believe the benefits outweigh the downsides, especially if we keep the guides straightforward and highly illustrated.
• I have switched from the historically recommended Sourcetree to Git Extensions.
  To be extremely frank, Sourcetree is a proprietary, barely maintained, unstable piece of software. It is unnecessarily an extremely common pain point for users. Git Extensions has all the features of Sourcetree (and more), is equally user friendly, frequently updated, and FOSS. Git Extensions also utilizes your existing install of Git and PuTTY/Pageant, rather than installing its own customized version. While it will take some time for the community to learn/adapt to this recommendation, I believe it will be well worth it in the long-run. The main downside is that it is Windows exclusive.

Given that I am (for now) exclusively a Windows developer, input on the more generalized changes from Mac and Linux users would be highly appreciated.

Many of the images are still lacking alt text, which I'll add to this PR after I've received further input on the overall structure.

Thank you for your time!

[itinerare]

I don't have the wherewithal to go through this in depth at the moment, but just wanted to note quickly that-- provided sufficient documentation-- I do support switching our git GUI recommendation... With regards to it being Windows-exclusive, this isn't functionally different from Sourcetree, so it is at worst no better or worse than now.

[perappu]

After some discussion in Discord, made the decision to split the guide into "Software Setup" and "Environment Setup".

[LokivirART]

As I was making my way through the guide, here are some notes I thought of to help make things more clear / etc ! Sorry if this is a bit overboard in any way, I just want to make sure it is 100% as clear as possible to someone who maybe has literally no idea what they're doing lol. Hopefully this feedback is helpful :D

---> INSTALLING XAMPP

Step 2 : i would personally write "If you see this warning, as long as you follow this guide, you can ignore it and hit "OK"". Just to make it clear whether you should x out or hit OK. Though I didn't test if the x works too sooo..

Step 7 : After installation was complete, I had the following popup automatically : https://f2.toyhou.se/file/f2-toyhou-se/images/106975829_jfcjpeNuNIdbBEk.jpg (my laptop wouldn't let me take a screenshot so excuse the fact it's a photo lmfao)
I'd clarify what to do here for any other users who may receive the same or similar popups.

Step 8 : Add "Click Finish"

Step 9 : in the bold text, add "You may have to click "Show more" to see these options."

---> CONFIGURING XAMPP

Step 2 : You wrote "upload_max_size" in the text, but in the file it's actually called "upload_max_filesize"

Step 4 : Reorder text to say "Save your changes and then close this file."

Step 5 : Your text says "http.conf" but the option is actually "httpd.conf"

Step 6 : I noticed in your instructions the slashes are \ , but when I opened the file my slashes were / . Not sure if this makes any difference or not. I followed your version in the instructions though (not really sure if this needed to be pointed out or not but I figured I may as well note it)

Step 7 : Reorder text to say "Save your changes and then close this file."

MAJOR ISSUE (from my understanding) you cannot restart Apache like it says to do in step 7 with the changes made to the config files . It expects you to already have cloned lorekeeper to your device, but that step doesn't actually happen until part 2 of the guide "Development Environment Set-up" , so these steps are out of order I suppose

EDIT : As of this comment I did not get farther than this step, but I will continue reviewing soon !

[LokivirART]

More stuff , moving on to the dev part of the guide after this !

---> INSTALLING GIT

Step 2 : When I ran it, it once again asked me if I wanted to allow changes to my device . I'd just put a note saying to click yes if you get that popup .

Additionally, after I select next on this step, it brings up a "select destination location" page, with the default being C:\Program Files\Git . I'd clarify if it should go there or another location .

Step 3 : After hitting next, the next page is "Select Start Menu Folder" . It automatically sets it as "Git"

Step 8 : Mine actually defaulted to "Use the native windows secure channel library" as opposed to "use the openSSL library" , so I'd just say which one to use instead of saying "default" since that can apparently vary

Since this seems to vary for at least some options by computer, I'd honestly just remove the term "default" from all these steps and just specify exactly what the person should select :]

---> INSTALLING GIT EXTENSIONS

Step 6 : After hitting next on this screen, I get a page that says "Telemetry Privacy Policy" which I believe allows you to select or not select allow. Dunno if that should be mentioned?

Step 7 : Once again got the "allow this app to make changes to your device" notification

Step 8 : Same as Step 7

Link at the very bottom of the page doesn't work btw ! "setting up your local copy of Lorekeeper (http://127.0.0.1:8000/lk-docs/guides/software-setup/software-windows/guides/setup-index/#development-environment-set-up)" I'm assuming it's supposed to go here ? http://127.0.0.1:8000/lk-docs/guides/dev-setup/dev-windows/

[LokivirART]

more notes :3

---> COPYING LOREKEEPER

Step 4 : "Next, click "Browse" next to the Destination."
My htdocs folder didn't actually exist for some reason? However, just typing it in seemed to work for now...
Maybe a note that if the folder doesn't exist yet, to just type it in and it'll be created for you?

---> INSTALLING COMPOSER

Step 3 : I got tha popup once again "Do you want to allow this app to make changes to your device"

--> INSTALLING VSC

Step 2 : I know it's probably obvious but you didn't specify to open the newly downloaded file like you had in previous ones lol.

Step 6 : You actually have to log in to disable copilot,,, wth lol. Anyways I'd just give some info about that ? It prompts you to "continue with github" or "continue with GHE.com" or "skip for now" (the latter of which doesn't seem to disable copilot)

---> RUNNING LOREKEEPER

Step 2 : After open with code, i got a popup in VSC "Do you trust the authors of the files in this folder?" . Options include a checkbox for "Trust the authors of all files in the parent folder htdocs" and then you can choose "Yes, I trust the authors (trust folder and enable all features)" or "No, I don't trust the authors (Browse folder in restricted mode)" . Specify which one to select if it matters

Step 10 : php artisan migrate gave me an error, this fixed it for me https://teamtreehouse.com/community/mysql-is-not-recognized-as-an-internal-or-external-command-operable-program-or-batch-file

---

final comments... took me about 3 hours total to get through everything, with only two hiccups iirc ! my main point of concern is the xampp apache config that i mentioned in a previous comment . the first software guide took about 2 hours whereas the dev guide took me about 1 hour. Not sure if this information is relevant at all, but might be good to know ?

Anyways hopefully at least some of what I've commented about on here is helpful ahahh....

[perappu]

Huge thank you for the feedback @LokivirART -- I updated the guide accordingly and have otherwise begun to enter the polish stage, so I'm bringing this out of the draft stage!

[perappu]

Found a multiplatform (!) FOSS graphical git client that I quite like called SourceGit, and it's even easier to use than Sourcetree and Git Extensions, so I updated the guide to use those instead.

Also shuffled around the way images were stored/organized.

[itinerare]

I'm so excited about potentially being able to recommend one git client for all platforms you don't even know

[itinerare]

Looks good to me! I figure it's about at the point where if we want to jostle the structure more, it'll be easier to do in subsequent PRs/with this material already incorporated.