Created on September 5, 2018 for macOS High Sierra
- Quick link: Make changes and submit a pull request
- Quick link: Test a pull request
Xcode is a set of developer tools provided by Apple, but not installed by default.
To see if you have Xcode installed:
xcode-select --install
Homebrew helps us install the open-source tools we'll use.
To see if you have Homebrew installed:
brew -v
To install Homebrew:
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
Git is a command line tool that lets us version control our projects.
To see if you have Git installed:
git --version
To install git:
brew install git
Git Cola is a Git GUI for Mac.
To install Git Cola:
brew install git-cola
If you have two-factor authentication enabled for GitHub, you'll need to set up a personal access token as a special command-line version of your GitHub password. Follow GitHub's instructions to create a personal access token, and save it to your password manager.
Optionally, you can follow the longer process to set up an SSH key in GitHub and avoid using a password:
- https://help.github.com/articles/checking-for-existing-ssh-keys/
- https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/
- https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/
Choose a place where you want to keep your GitHub project folders, and navigate there in a terminal.
For example:
cd Documents
Create a local copy of the project:
git clone git@github.com:sensu/website.git
Then navigate to the project folder:
cd website
Check to see if you have Middleman installed:
middleman version
Check to see if you have Bundler installed:
bundle -v
Install project dependencies:
bundle install
Run Middleman locally:
bundle exec middleman
You can now view the site in your browser at the address specified in the command output.
Use CTRL+C to exit Middleman and run other commands.
See what branch you're on:
git branch
Switch to the master branch:
git checkout master
(If it gives you trouble here, it's probably because you have changes that Git doesn't want to lose. To go ahead anyways and lose any changes, use git checkout master --force.)
Sync your local project folder with GitHub:
git fetch origin
Then reset your master branch to be the same as the one in GitHub:
git reset origin/master --hard
Finally, create a working branch and check it out:
git checkout -b branch-name
Use a text editor like Atom or Visual Code Studio to edit the project files.
Run the project locally and preview your changes:
bundle exec middleman
Use CTRL+C to exit Middleman and run other commands.
When you're ready to save, run Git Cola:
git cola
And user the interface to stage and commit your changes.
See what branch you're on:
git branch
Make sure you're on a working branch and not the master branch.
See your recent saved changes (commits):
git log
If the recent commits look good, go ahead and push your working branch to GitHub:
git push origin branch-name
Now navigate to the main page of the project and follow the prompts to open a pull request.
Get the latest copy of all branches pushed to the project on GitHub:
git fetch origin
You should see the branch that you need to test listed there. Check it out using its name:
git checkout pull-requested-branch-name
Make sure you see the recent changes you except to see:
git log
Use q to exit the log.
Run the project locally:
bundle exec middleman
If everything looks good in your browser, go ahead and approve the pull request in GitHub. Don't forget to use CTRL+C to exit Middleman when you're done.