I'm trying to work my way through BUILD.md, and I'm still running into problems, probably due to the fact that I'm running the macOS 11 beta. I'm currently waiting for the latest Xcode GM to download, but in the meantime, here are my thoughts on BUILD.md...
- I think the "Required dependencies" should be titled "Install Build Dependencies".
- It should have a section for each build platform.
- It should explain explain how to install each dependency if it can be installed with a single command-line command.
- In the case of macOS, since Cocoapods is already installed with
brew, it would be simplest if everything else was also installed with brew.
- There should also be explicit instructions to download an appropriate IDE. In the case of macOS and iOS, it seems like it is also necessary to download Xcode, so that should be spelled out, as well.
Here's a sample set of instructions for macOS:
1. Set up your workspace
Note: you will need a GitHub account in order to work on Joplin. A GitHub account is very useful: you can even use it to sign up for the Joplin Forums, as well!
-
Install wei/pull and enable it for your new fork. If this is the only thing you're working on on GitHub, it should be safe to enable it for all future branches, as well.
-
Navigate to the page for your new fork on GitHub (https://github.com/<your_username>/Joplin), click the green Code button:
and select Open with GitHub Desktop:
Follow the instructions to create a local copy (clone) of the repository on your Mac.
Note: you should not put a cloned repository inside any folder that syncs with another cloud service, as the cloud sync may confuse GitHub. A safe place to clone your Joplin repository is <home_folder>/Repositories/Joplin
2. Install the Build Dependencies
-
Open Applications / Utilities / Terminal for the following steps. Copy and paste each command into the terminal window and press ⏎ to continue:
-
Install Homebrew:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
Homebrew will let you install the rest of the dependencies more easily.
-
Install Yarn:
brew install yarn
-
Install Node.js:
brew install node
-
Install Cocoapods:
brew install cocoapods
3. Finishing Your Setup and Testing Your Workspace
-
Launch Visual Studio Code, select File > Open... (⌘O), navigate to the folder where GitHub cloned your Joplin repository, and click Open.
-
Open a new terminal window in VS Code with Terminal > New Terminal (⌃⇧`) to enter the following commands.
-
Finish your setup by installing the rest of Joplin's dependencies using npm:
npm install
-
Test that your workspace is correctly set up by building and running the existing code for Joplin for Mac as-is:
cd ElectronClient
npm start
The above command should launch a working copy of Joplin. If it doesn't, copy any feedback from the terminal window into your clipboard and search for it on the Joplin Development Forums. If you don't find a solution to your problem, start a new topic, and paste the terminal output in full. Your report will help us make sure these instructions are up-to-date and functional!
4. Working On Code
- In order to minimize conflicts with existing code, you use a separate branch of your repository for each feature or fix you are working on.
- To open a new branch, in GitHub Desktop, click Current Branch:
and select New Branch:
Enter a descriptive name for the feature you plan on working on, with hyphens instead of spaces, and click Create Branch:
- To use a branch you have already made, in GitHub Desktop, click Current Branch:
start typing the name of the branch and click on it to switch.
If you have unsaved work in an existing branch, GitHub Desktop will offer to stash it on your computer until you switch back to that branch.
- When you are done working, you can commit your changes to a branch by selecting the files in GitHub desktop, entering a summary of your changes, and clicking Commit to <name of branch>:
If the Commit button shows the wrong branch, you should be able to switch branches (see above) and commit your changes to the correct branch.
Note: because commits create a history of your work that allows you to revisit any problems later on, it can be useful to err on the side of creating commits as often as possible when you have made changes worth summarizing.
...
...
...
How's this to start? Can you tell I've read a lot of Dummies books in the past? 
(I actually really would appreciate feedback on this.)
2 Likes
