Deprecation Warning

The Swift Education materials are out of date, and are no longer maintained.

Swift Education Web Site

This is the source code for generating the static content for the Swift Education web site hosted via GitHub Pages.

Organization

Everything in the master branch is publicly accessible via http://swifteducation.github.io. However, do not manually add html files and other assets to this branch! Everything on master should be a result of site generation via the develop branch.

The develop branch contains the actual source code for the web site. It is within the develop branch that you should make any changes, and generate the results in the build directory, which then gets committed and pushed to master. To learn more about this workflow, first set up your development environment, and then try making a change following the workflow tutorial.

Set Up Your Development Environment

This web site uses the Ruby Middleman gem for static site generation. Doing so allows you, the developer, to think in terms of templates and other features usually found in dynamic server-side frameworks. You should know, or be prepared to know, a little about Ruby, HAML, Compass/SASS, and the typical client-side web stack (HTML5, CSS, JavaScript). Due to its influence on Middleman, having experience with Rails is a plus, but is not required. Learning how to use Middleman itself is fairly easy.

Steps

1. You should have Ruby 2.2.2+ and Bundler installed (gem install bundler).
2. Clone the repository: git clone [email protected]:SwiftEducation/SwiftEducation.github.io.git.
3. Check out the develop branch (git checkout develop). The rule of thumb is "always be working in develop or a branch off of develop."
4. Install the dependencies: bundle install.
5. Note that the develop branch .gitignore is set to ignore the build directory. This is correct.
6. From within the repository root, clone the repository again, placing it within a build directory. Yes, really: git clone [email protected]:SwiftEducation/SwiftEducation.github.io.git build. The rule of thumb here is "build should always be on the master branch."

What you have done here is created a local repository for the web site, where you will be working in the develop branch. Once you have finished your changes, you will run middleman build. This will translate the code in source into static files that reside in build. The build directory is bound to the master branch. After running middleman build to generate a new static site in the build directory, you should cd into the build directory, commit and push. This will push the new static site to the master branch on the remote (GitHub), which will then be visible at http://swifteducation.github.io.

Workflow Tutorial

This development environment configuration may seem a little strange, but is actually a simple method for using Middleman with GitHub Pages for organizations. To help reify this, let's walk through a simple change.

1. In one console, checkout the develop branch and run middleman server from the repo root. Keep this running, and use another console for everything else.
2. Visit http://localhost:4567 in your browser, and observe the web site. (If something doesn't look right, then do not continue. Either your environment isn't right, you didn't run middleman server from the repo root, or this documentation is wrong.
3. Verify that you are on the develop branch, and make a change. For example, add an innocuous HTML comment to the bottom of source/layouts/layout.html.haml.
4. Visit http://localhost:4567 in your browser, view the source of the page, and observe the change you made.
5. Once you are done, commit your change. You have just committed a source change to the develop branch.
6. Push your local develop branch to the develop remote on GitHub: git push origin develop.
7. Visit http://swifteducation.github.io and notice that your changes do not appear on the web site. Why is this? Because you made a change to the develop branch, which is right, but GitHub Pages for organizations reflects the master branch. The next step is to get your changes into master.
8. Run middleman build. This will generate a new static site in the build directory.
9. cd into the build directory and run a git diff. If things seem as expected, commit and push.
10. Visit http://swifteducation.github.io and notice that your changes appear on the web site.

Issues and Conventions

Try to create a well-described issue for a feature before implementing the change in the develop branch. Commits related to the issue should use a commit message prefixed with Issue #N. Commits that resolve an issue should use Fixes #N in the message, typically as the prefix. See the log for examples.

Commit messages should use present tense. For example, "Correct missing giraffe and add new gerbil," rather than "Corrected missing giraffe..." or "Correcting missing giraffe."

Contributing

Improvements and corrections are welcome! Simply fork this repository, make your changes on the develop branch, and create a pull request for the upstream develop branch (not master). If your PR is merged into the develop branch, you can expect that the site generation will be run, and that your changes will be reflected on master (and, therefore, the web site).

---

Copyright © 2015 Apple, Inc. All rights reserved.