Starting a New Project
Before you start, you'll need:
- A working text editor and FTP access
- A Git client, such as Tower
- Your very own SSH key
- Node and Node Package Manager
In this document, we'll cover:
Request and clone a new Git repository
Create the new Responsive theme
Commit and push your changes to Git
Set up your user-facing documentation
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.
Request a new Git repository in #interactive-design. This is what Tower will look at to see if you've made any changes in your code on your machine.
Example: "Can I get a new Git repository for r-research?" Always prefix your child theme names with
r-, and use a name that makes sense for the project. When in doubt, take a look at your URL and see what the site name is.
You will be sent a URL to a shiny, new, blank Git repository. Go to your new repository and find the SSH clone URL to the right. Copy this URL (be sure it's not HTTPS).
In Tower, go to your Repositories pane, and hit "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.
Error: Host Key Verification Failed.
If you're still having issues after following the process for setting up your SSH key, try running the following in your terminal to add github to your systems SSH Known Hosts list:
ssh-keyscan -t rsa github.com >> ~/.ssh/known_hosts
Once you have everything as you like it, go ahead and hit clone.
Why can't I use the https URL? Security, yo.
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.
Download and unzip the responsive-starter theme into the same folder you cloned your new Git repository into. This gives you some base files to start your new theme.
It’s best to always download directly from the responsive-starter theme so that you are always starting with the latest version of Responsive.
Update the following files with these items:
-
Theme Name:Replace "Responsive Child Starter" with the theme name you want to show in the Wordpress admin. Use this convention: Your Name Here (R) -
Description:Replace "Enter child theme description here" with the description you want to show in the Wordpress admin. Use this convention: A Responsive Framework child theme for Your Theme Name
-
"name":Replace "responsive-child-starter" with your theme name (r-yournamehere) -
"description":Replace "A starting point for Responsive Framework child themes." with the same description you used above -
"repository":Replace "https://github.com/bu-ist/responsive-child-starter/" with the URL to your repository -
"contributors":Replace"Your Name <[email protected]>"with your 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.
Update this file with a summary of what site your theme is for and what functionality your theme adds, if any.
Don't forget to add a screenshot of the final design! No one likes to see an empty thumbnail in the Wordpress theme directory. Do yourself a favor and make one now from your homepage mockup. See Wordpress's screenshot recommendations for more information.
What about bower_components? You don’t need to update anything within the bower_components folder. These are files the rest of your theme is dependent on. In general, it’s best to leave these files alone so that you can update the Responsive framework without worrying about overwriting something you’ve done.
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, and then go to Finder and drag and drop the theme code folder into your Terminal window, like so:
Press enter, 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.
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.
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.
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).
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!