Simplify SETUP.md for MacOS #57528

snickell · 2024-03-26T03:24:22Z

Its probably easiest to read this PR with the markdown rendered, possibly as side-by-side before/after blocks:
Before | After

Changes:

Don't suggest using Rosetta for Apple Silicon (not needed anymore, much faster)
Shorter + less complex + visually clearer = easier to follow
Use multi-line code blocks for macOS setup commands, as these are easier to single-click copy-paste, and perhaps less visually overwhelming:
Suggest the repo be checked out BEFORE doing platform-specific setup. Why? While this complicates git lfs slightly (requires an explicit git lfs pull), it means the instructions are actually valid / they work... since nvm install and rbenv install don't actually work until the repo is checked out (as they use .nvmrc and .ruby-version).
brew install packages in one big block at the start (just like we do for apt-get install on ubuntu), rather than having to tediously paste in 20 brew install commands one by one as you come to each.
Remove now unnecessary build hacks from "Apple Silicon (M1) or Intel Mac bundle install steps" section from the end.
Move bundle exec rake install tips (equally relevant to all OSes) out of the linux-only section
Install brew pdftk-java (which automatically pulls in a cpu-correct jdk) rather than complex instructions to install intel-only jdk8
More consistently use the very nice <summary></summary> formatting for troubleshooting tips

Testing:

Instructions work on a fresh user account on an apple silicon macbook running macOS 14
~~- [ ] Instructions work on a fresh user account on an x86 macbook (preferably running macOS 13)~~ Update setup.md for an M3 mac #58321 removed x86 as supported
pdftk can still generated curriculum pdfs (how to test this?)

snickell · 2024-03-26T05:40:08Z

SETUP.md

-1. Clone the repo, which also may take a while.
-    - Note you should have `git lfs --version` >= 3.0 installed prior to cloning, see OS-specific install steps referenced above.
-    - The simplest option is to clone via SSH with: `git clone git@github.com:code-dot-org/code-dot-org.git`
-    - The fastest option is to clone via HTTP with: `git clone https://github.com/code-dot-org/code-dot-org.git`. Although faster than SSH, this option requires you to reauthenticate every time you want to update. You will therefore probably want to switch to SSH after the initial clone with `git remote set-url origin git@github.com:code-dot-org/code-dot-org.git`


We now suggest cloning the repo before doing os-specific steps. While this requires adding a git lfs pull below, it means that nvm install and rbenv install actually work in the OS specific sections. i.e.: this ordering is actually correct!

should we list git lfs in the dependency check instructions above?

snickell · 2024-03-26T05:40:56Z

SETUP.md

-1. `gem install bundler -v 2.3.22`
-
-1. `rbenv rehash`
+1. `gem install bundler -v 2.3.22 && rbenv rehash`


Collapse gem install bundler and rbenv rehash together: they're really one command, as the rbenv rehash is there to make the new bundler command "take".

snickell · 2024-03-26T05:41:57Z

SETUP.md

-      <summary>Troubleshoot: `rake aborted! Gem::LoadError: You have already activated...` </summary>
-
-      - If you have issue `"rake aborted! Gem::LoadError: You have already activated rake 12.3.0, but your Gemfile requires rake 11.3.0."`, make sure you add `bundle exec` in front of the `rake install:hooks` command
-    </details>


The bundle exec is now explicitly present in the command (in an older version SETUPers were left to add the bundle exec, so this troubleshooting tip was relevant if you forgot)

snickell · 2024-03-26T05:42:31Z

SETUP.md

+        If, for any reason, you are forced to interrupt the `bundle exec rake install` command before it completes,
+        cd into dashboard and run `bundle exec rake db:drop` before trying `bundle exec rake install` again.
+        `bundle exec rake install` must always be called from the local project's root directory, or it won't work.
+    </details>


This section comes from the linux-specific instructions. Its a good tip, but its not just linux-specific, so here we make it available to all platforms.

snickell · 2024-03-26T05:43:53Z

SETUP.md

-1. Install necessary plugins described in the [Editor configuration](#editor-configuration) section below.
-
-After setup, read about our [code styleguide](./STYLEGUIDE.md), our [test suites](./TESTING.md), or find more docs on [the wiki](https://github.com/code-dot-org/code-dot-org/wiki/For-Developers).
+After setup, [configure your editor](#editor-configuration), read about our [code styleguide](./STYLEGUIDE.md), our [test suites](./TESTING.md), or find more docs on [the wiki](https://github.com/code-dot-org/code-dot-org/wiki/For-Developers).


I think its kind of ugly to have a not-very-clear "setup your editor" section included as a step: this step is unlike the other explicit commands, and it detracts from the "SETUP.md got dashboard running!" nice ending to the steps. I think its more of a follow-on, and its not really required anyway.

snickell · 2024-03-26T05:44:29Z

SETUP.md

@@ -104,102 +101,86 @@ External contributors can supply alternate placeholder values for secrets normal

 ### macOS

-These steps are for Apple devices running **macOS Monterey and Ventura**, including those running on [Apple Silicon (M1|M2)](https://en.wikipedia.org/wiki/Apple_silicon#M_series). 
+Setup steps for Apple devices running **macOS Ventura and Sonoma**, including those running on [Apple Silicon](https://en.wikipedia.org/wiki/Apple_silicon#M_series) and Intel x86:


Include last two current macOS versions, explicitly mention that these instructions should (still) work on an x86 mac.

snickell · 2024-03-26T05:45:12Z

SETUP.md

-       cd into dashboard and run `bundle exec rake db:drop` before trying `bundle exec rake install` again
-    1. `bundle exec rake install` must always be called from the local project's root directory, or it won't work.
-    1. Finally, don't worry if your versions don't match the versions in the overview if you're following this method; the installation should still work properly regardless
+1. Return to the [overview](#overview) and continue setup.


This note was not linux specific, but its a great tip: its been moved to the shared setup instructions as a troubleshooting tip for bundle exec rake install

snickell · 2024-03-26T05:46:17Z

SETUP.md

-```
-
-
-### ImageMagick with Pango


I started fresh, cleared my ~/.rbenv, and I'm pretty sure this is no longer necessary. Brew was messing up the openssl include and library path before (couple years past), but its straightened out now. Explicitly updating ffi is no longer required, our Gemfile.lock version is plenty fresh.

snickell · 2024-03-26T05:46:59Z

SETUP.md

-
-
-### ImageMagick with Pango
+#### ImageMagick with Pango


Use the same #### column indent as other sections, so they don't become subsections of imagemagick with pango by accident

snickell · 2024-03-26T05:48:56Z

SETUP.md

@@ -104,102 +101,86 @@ External contributors can supply alternate placeholder values for secrets normal

 ### macOS


macOS section

For the macOS specific section, the changes are extensive, and I think its much easier to look at the markdown rendered versions before and after side by side, rather than trying to stare through the diff noise:
Before | After

snickell added 11 commits March 25, 2024 20:08

Update macOS SETUP.md steps

b297b82

Install pdftk-java with brew, not jdk8 manually

4c43933

Install bundler & rehash are really a one-liner

89e650b

macOS not OSX

fd43c37

Cleanup

fcac06f

Try using a block format for easier copy-paste

b66c47b

multi-line are easier to copy

8214639

More block quotes

18efd8c

Specify version files

0b83c19

remove misplaced `

726628e

Bold

0f25552

snickell commented Mar 26, 2024

View reviewed changes

snickell requested a review from cat5inthecradle March 26, 2024 05:51

SETUP.md: instruct to check git lfs version

106c1ff

snickell requested review from sureshc and molly-moen May 4, 2024 02:51

Merge branch 'staging' into seth/no-rosetta

c4d1466

snickell marked this pull request as ready for review May 4, 2024 02:56

Merge branch 'staging' into seth/no-rosetta

7a48bb0

cat5inthecradle approved these changes May 7, 2024

View reviewed changes

stop specifying MySQL 5.7 on macOS

84543c6

snickell merged commit 6dd379f into staging May 7, 2024
2 checks passed

snickell deleted the seth/no-rosetta branch May 7, 2024 21:39

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Simplify SETUP.md for MacOS #57528

Simplify SETUP.md for MacOS #57528

snickell commented Mar 26, 2024 •

edited

snickell Mar 26, 2024

cat5inthecradle Mar 26, 2024

snickell May 4, 2024

snickell Mar 26, 2024

snickell Mar 26, 2024

snickell Mar 26, 2024

snickell Mar 26, 2024

snickell Mar 26, 2024

snickell Mar 26, 2024

snickell Mar 26, 2024

snickell Mar 26, 2024

snickell Mar 26, 2024 •

edited

		@@ -104,102 +101,86 @@ External contributors can supply alternate placeholder values for secrets normal

		### macOS

Simplify SETUP.md for MacOS #57528

Simplify SETUP.md for MacOS #57528

Conversation

snickell commented Mar 26, 2024 • edited

Changes:

Testing:

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

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

snickell Mar 26, 2024 • edited

Choose a reason for hiding this comment

macOS section

snickell commented Mar 26, 2024 •

edited

snickell Mar 26, 2024 •

edited