Ghost/CONTRIBUTING.md

Contributing to Ghost

So you're interested in giving us a hand? That's awesome! We've put together some brief guidelines that should help you get started quickly and easily.

Reporting An Issue

If you think you've found a problem with Ghost, or you'd like to make a request for a new feature in the codebase… please follow these steps:

1. Search for existing issues - The most important step! Help us keep duplicate issues to a minimum by checking to see if someone has already reported your problem or requested your idea.
2. Describe your issue in detail - Help us help you. Before opening any issue, please read the Issue Guidelines, written by Nicolas Gallagher. Include operating system and version, browser and version, version of Ghost, customized or vanilla build, etc. where appropriate. Also include steps to reproduce the bug.
3. Include a screencast if relevant - Is your issue about a design or front end feature or bug? The most helpful thing in the world is if we can see what you're talking about. Use LICEcap to quickly and easily record a short screencast (24fps) and save it as an animated gif! Embed it directly into your GitHub issue. Kapow.

Working on Ghost Core

Note: It is recommended that you use the Ghost-Vagrant setup for developing Ghost.

Pre-requisites:

• node > 0.10 and < 0.11.4
• ruby and the gems 'sass' and 'bourbon'
• for running functional tests: phantomjs 1.9.* and casperjs 1.1.* (instructions)
• for building docs: python and pygments

Installation / Setup Instructions

1. Clone the git repo
2. cd into the project folder
3. Run git submodule update --init
4. Run npm install -g grunt-cli
5. Run npm install.
   • If the install fails with errors to do with "node-gyp rebuild" or "SQLite3", follow the SQLite3 install instructions below this list
   • Usually if you're within vagrant, and have installed the guest plugins and updated that, this will not happen
6. Run grunt init from the root - this installs Bourbon, compiles SASS and compiles Handlebars templates
7. Run npm start from the root to start the server.

Front-end can be located at http://localhost:2368, Admin is at http://localhost:2368/ghost/.

Whist developing you may wish to use grunt watch to watch for changes to handlebars and sass and recompile automatically, if you run Ghost in production mode, you will need to run grunt prod - please see the Grunt Toolkit docs.

Updating with the latest changes

Pulling down the latest changes from master will often require more than just a pull, you may also need to do one or more of the following:

• npm install - fetch any new dependencies
• git submodule update - fetch the latest changes to Casper (the default theme)
• grunt - will recompile handlebars templates and sass for the admin (as long as you have previously run grunt init to install bourbon)
• delete content/data/*.db - delete the database and allow Ghost to recreate the fixtures

Key Branches & Tags

• master is the bleeding edge development branch. All work on the next release is here.
• gh-pages is The Ghost Guide documentation for Getting Started with Ghost.
• releases are used to contain stable tagged versions of Ghost.

Compiling CSS & JavaScript

A SASS compiler is required to work with the CSS in this project. You can either do this by running grunt from the command line - or by using a 3rd party app. We recommend CodeKit (Paid/Mac) & Scout (Free/Mac/PC). You will need to have Ruby installed, as well as having run gem install sass && gem install bourbon.

Coding standards

Good, clear and consistent code styles are pivotal in the success of any software project. Good use of style can reduce errors, consistency will enable us to work together efficiently.

JavaScript

• JSLint is King (see JSLint section below).
• Use strict mode
• Protect the global scope
• Indent with 4 spaces
• Max line length 120
• Use unix line endings
• Document as you go - we are using groc and jsdoc formats
• Write tests, unit tests are written in Mocha using spec style, functional tests use Casper.js

For more in depth information please read the official Ghost Coding Standards.

HTML & CSS

• 4 spaces for HTML & CSS indentation. Never tabs.
• Double quotes only, never single quotes.
• Use tags and elements appropriate for an HTML5 doctype (e.g., self-closing tags)
• Adhere to the Recess CSS property order.
• Always a space after a property's colon (.e.g, display: block; and not display:block;).
• End all lines with a semi-colon.
• For multiple, comma-separated selectors, place each selector on its own line.

For more in depth information please read Mark Otto's excellent Code Guide

Submitting Pull Requests

The easier it is for us to merge a PR, the faster we'll be able to do it. Please take steps to make merging easy and keep the history clean and useful.

Firstly, always work on a branch, it will make your life much easier - honest. Not touching the master branch will also simplify keeping your fork up-to-date.

Note: If you are not comfortable with git & using rebase, make a special 'merge' branch of your branch to do these things on, then if something goes awry you can always go back to your working branch and try again.

Clean-up history

Whilst you're working on your branch on your own, you can do all the commits you like - lots of little commits are highly recommended. However, when you come to submit a PR, you should clean your history ready for public consumption.

• Run git log master..your-branch-name to see how many commits there are on your branch
• Run git rebase -i HEAD~# where # is the number of commits you have done on your branch

Use the interactive rebase to edit your history. Unless you have good reason to keep more than one commit, I recommend marking the first commit with 'r' and the others with 's'. This lets you keep the first commit only, but change the message. You commit message(s) should follow the pattern described in the notes above. The first line of your commit message will appear in the change log which goes out to our VIPs with each pre-release, so please keep that in mind.

Check it passes the tests

Run grunt validate to check that your work passes JSLint, the server-side mocha unit tests, and functional tests written in casperjs. If this fails, your PR will throw an error when submitted.

Need Help?

If you're not completely clear on how to submit / update / do Pull Requests, please check out our in depth Git Workflow guide for Ghost.

Grunt Toolkit

Ghost uses Grunt heavily to automate useful tasks such as building assets, testing, live reloading/watching etc etc

Grunt Toolkit docs are a worthwhile read for any would-be contributor.

Troubleshooting / FAQ

I get "ERROR: Failed to lookup view "index"

Sounds like you don't have our default theme - Casper, your content/themes/casper folder is probably empty. When cloning from GitHub be sure to use SSH and to run git submodule update --init. Don't use the release zip file on GitHub, if you want a zip file use the one from Ghost.org.

I get "Syntax error: File to import not found or unreadable: bourbon/_bourbon."

Sounds like you don't have the Ruby gem "bourbon" installed. Make sure you have Ruby, and then run gem install bourbon.

Ghost doesn't do anything - I get a blank screen

Sounds like you probably didn't run the right grunt command for building assets

SQLite3 doesn't install properly during npm install

Ghost depends upon SQLite3, which requires a native binary. These are provided for most major platforms, but if you are using a more obscure *nix flavor you may need to follow the node-sqlite3 binary instructions.

Contributor License Agreement

By contributing your code to Ghost you grant the Ghost Foundation a non-exclusive, irrevocable, worldwide, royalty-free, sublicenseable, transferable license under all of Your relevant intellectual property rights (including copyright, patent, and any other rights), to use, copy, prepare derivative works of, distribute and publicly perform and display the Contributions on any licensing terms, including without limitation: (a) open source licenses like the MIT license; and (b) binary, proprietary, or commercial licenses. Except for the licenses granted herein, You reserve all right, title, and interest in and to the Contribution.

You confirm that you are able to grant us these rights. You represent that You are legally entitled to grant the above license. If Your employer has rights to intellectual property that You create, You represent that You have received permission to make the Contributions on behalf of that employer, or that Your employer has waived such rights for the Contributions.

You represent that the Contributions are Your original works of authorship, and to Your knowledge, no other person claims, or has the right to claim, any right in any invention or patent related to the Contributions. You also represent that You are not legally obligated, whether by entering into an agreement or otherwise, in any way that conflicts with the terms of this license.

The Ghost Foundation acknowledges that, except as explicitly described in this Agreement, any Contribution which you provide is on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.