Starting a New Project

Request and clone a new Git repository

To track your changes, Tower needs to know two things – what Git repository it should compare your code to, and where your code lives on your computer. These steps take care of that.

Clone the Repository with Tower

In Tower, go to your repositories pane, find your repository and click “Clone.”

Enter your SSH URL in the dialog that comes up. You should see something akin to the following screen:

(If you don’t have anything under SSH-Keyfile, now is a good time to generate that SSH key. You can check if you have an SSH key here.)

Once you have everything as you like it, go ahead and hit Clone.

Create the New Theme

Even though you cloned the new repository, you still don’t have any files to edit. That’s because the repository you just cloned from is blank. It’s up to you to add files – the new child theme – to your repository.

Get Your Starter Files

Download and unzip the responsive-child-starter-3x theme into the same folder you cloned your new Git repository into. This gives you some base files to start your new theme.

Always download directly from that repository so you’re always starting with the latest version of Responsive Foundation & Framework.

Update the Files

Update the following files with these items:

css-dev/style.scss

• Theme Name: Replace Responsive Child Starter with the theme name you want displayed in the WordPress admin that lists themes. Use this convention: {School Name} (R3)
• Description: Replace Enter child theme description here with the description you want displayed in the WordPress admin. Use this convention: A Responsive Framework 3x child theme for {School Name}.
• Template: Make sure it’s set to responsive-framework-3x.

package.json

• "name": Replace responsive-child-starter with your theme name r3-{schoolname}
• "description": Replace A starting point for Responsive Framework child themes. with the same description used for style.scss.
• "repository": Replace “https://github.com/bu-ist/responsive-child-starter-3x” with the URL to your project’s GitHub repository.
• "contributors": Replace Your Name <you@bu.edu> with your BU name and email address.

Adding contributors: This is your – and your friendly coworkers’ – time to shine! You can add more than one contributor – just separate email/name pairs with a comma. For example, you might know a designer or developer who will be working on the theme with you later. Now is a good time to add them so you don’t forget.

readme.md

Update this file with a summary of what site your theme is for and what functionality your theme adds, if any.

screenshot.png

Don’t forget to add a screenshot of the final design’s mockup! An empty thumbnail in the WordPress theme directory doesn’t do anyone any favors. Make one from your homepage mockup. See WordPress’s screenshot recommendations for additional info regarding formatting.

Install Development Dependencies

Just as you should always get the newest version of the starter theme, you should always get the latest version of your dependencies by running npm install.

In Terminal:

Change to the folder that holds your theme code. You can do this by typing cd, then go to Finder and drag and drop the repository folder into your Terminal window, like so:

Press return, then run the following commands one by one:

npm install

This will install your dependencies. Once everything has successfully installed, run the following command:

grunt build

This takes care of your initial build. You should see several new files, including style.css, style.css.map, and a number of similar files. If you don’t encounter any errors (warnings are okay), continue on…

Commit and push your changes to Git

Stage your changes

Before you can commit your new files to Git, you’ll need to stage your changes. As you work on your theme, staging will give you an opportunity to review the changes in the code before committing them.

• In Tower, within your Working Copy, you should see a number of new changes ready to stage and commit.
• Stage your changes by clicking “Stage All.”

There isn’t a need to review your files at this point, but it can be helpful in future stage/commits to look at your changes before you write your commit subject if you didn’t commit for a while and forgot what you worked on.

Commit your changes

Write a brief, but descriptive commit subject. In this case, use “Initial commit.” You don’t need to fill out the detailed description.

In future commits, it’s good to have a descriptive commit subject so that if you ever need to roll back your changes, it’s easy to see exactly what point you need to roll back to.

You can commit as frequently or infrequently as you like, but a good guideline is to commit each time you switch from working on one “part” of the site to another. For example, if I were working on styles for the primary navigation for a while, and then decided I wanted to work on the homepage for a while, I’d probably do a commit after I finished my navigation work, but before I started my homepage stuff.

Once you’re ready, click “Commit.” This will commit your changes to your local repository.

Push your changes

Once you’re ready to make your changes available to others, you’ll want to push them. Now is a good time to push your initial commit by clicking “Push” at the top of the page.

You’ll see a dialog with some options. You can leave all these options alone and keep going. You’ll see this each time you do your first push to a new repository.

Push your changes each time you’d like them to be available to other designers and developers. This isn’t the same as making them live on a site – you’ll still need to either upload your files to NM (when you’re developing the site on our test servers) or request a deploy (when you want the changes to show up on staging or the live site).

Set Up Client-Facing Documentation

Finally, you’ll want to set up user-facing documentation right away so you can document your theme as you go.

The freshest base documentation is always available at http://wpdocs.bu.edu/.

Clone that site to http://wpdocs.bu.edu/{your-theme-name} and have a developer set up a documentation link in your admin bar.

When your theme is close to done: finalize your custom documentation and apply your new theme. It’s as easy as that!