Welcome to the contributing guide for Ghost!
So you're interested in giving us a hand? That's awesome! We've put together some guidelines that should help you get started quickly and easily. If you need help with anything, please come visit our slack community. Thank you for stopping by!
- feature roadmap
- feature wishlist
- slack community
- developer wiki
- community guidelines
- dev blog
If you need help with Ghost or have questions, please use slack (documentation is here). If you're raising a bug please be sure to include as much info as possible so that we can fix it! If you've got some code you want to pull request please squash commits, use this commit message format and check it passes the tests by running
grunt validate. Thanks for helping us make Ghost better.
There are lots and lots of ways to get involved, this document covers:
- raising issues
- working on Ghost core
- testing and quality assurance
- writing documentation
Reporting An Issue
If you're looking to raise an issue because think you've found a problem with Ghost, or you'd like to make a request for a new feature in the codebase, or any other reason… please read this first.
Please search for existing issues. Help us keep duplicate issues to a minimum by checking to see if someone has already reported your problem or requested your idea.
Please do not derail or troll issues. Keep the discussion on topic and respect the opinions of others.
A bug is a demonstrable problem that is caused by the code in the repository. Good bug reports are extremely helpful - thank you!
Guidelines for bug reports:
Use the GitHub issue search — check if the issue has already been reported.
Check if the issue has been fixed — try to reproduce it using the latest
masteror look for closed issues in the current milestone.
Isolate the problem — ideally create a reduced test case and a live example.
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.
Include as much info as possible! Use the Bug Report template below or click this link to start creating a bug report with the template automatically.
A good bug report shouldn't leave others needing to chase you up for more information. Be sure to include the details of your environment.
Here is a real example of a great bug report.
Template Example (click to use):
Short and descriptive example bug report title ### Issue Summary A summary of the issue and the browser/OS environment in which it occurs. ### Steps to Reproduce 1. This is the first step 2. This is the second step, etc. Any other info e.g. Why do you consider this to be a bug? What did you expect to happen instead? ### Technical details: * Ghost Version: master (latest commit: a761de2079dca4df49567b1bddac492f25033985) * Node Version: 4.4.7 * Browser: Chrome 48.0.2564.109 on Mac OS X 10.10.4 * Database: SQLite / MySQL
If you've got a great idea, we want to hear about it. Our user wishlist exists so that we can learn more about what our community wants us to build.
Please use your discretion to decide whether a feature request belongs on the wishlist or whether it's better suited to a GitHub issue.
Before making a suggestion, here are a few handy tips on what to consider:
Check out What makes it into Ghost core? - this explains the guidelines for what fits into the scope and aims of the project
Have a quick think about whether your feature is for the admin UI, the blog output, themes or apps - or does it affect multiple areas? This can help when describing your idea.
Remember, it's up to you to make a strong case to convince the project's leaders of the merits of a new feature. Please provide as much detail and context as possible, this means explaining the use case and why it is likely to be common. The strongest vote in favour of any feature request is hands-down, un-debatable traction on our user wishlist.
Change requests cover both architectural and functional changes to how Ghost works. If you have an idea for a new or different dependency, a refactor, or an improvement to a feature, etc - please be sure to:
Use the GitHub search and check someone else didn't get there first
Take a moment to think about the best way to make a case for, and explain what you're thinking as it's up to you to convince the project's leaders the change is worthwhile. Some questions to consider are:
- Is it really one idea or is it many?
- What problem are you solving?
- Why is what you are suggesting better than what's already there?
Submitting Pull Requests
Pull requests are awesome. If you're looking to raise a PR for something which doesn't have an open issue, please think carefully about raising an issue which your PR can close, especially if you're fixing a bug. This makes it more likely that there will be enough information available for your PR to be properly tested and merged. To make sure your PR is accepted as quickly as possible, please take a minute to check the guidelines on:
Testing and Quality Assurance
Never underestimate just how useful quality assurance is. If you're looking to get involved with the code base and don't know where to start, checking out and testing a pull request is one of the most useful things you could do.
If you want to get involved with testing Ghost, there is a set of QA Documentation on the wiki.
Checking out a Pull Request
The dev blog has detailed instructions on configuring your environment
to allow you to checkout pull requests with this simple command:
Ghost's developer documentation can be found at docs.ghost.org. These docs are written and hosted on readme.io which has a suggested edits feature through which you can submit updates. If you'd like to get more involved than just making amendments, email support and let us know :)
Full documentation on contributing translations can be found at http://docs.ghost.org/translations
Working on Ghost Core
Looking to get setup to work on Ghost? AWESOME! The Ghost-Vagrant image is a super-easy way to get a ready-made environment for contributing, but if you'd rather install Ghost natively, here's how...
What you'll need:
- A supported Node.js version & npm (see Supported Node Versions)
- phantomjs 2.1.x (instructions) for running tests
Installation / Setup Instructions
- Check you have the pre-requisites listed above!
git clone https://github.com/TryGhost/Ghost.git- clone the git repo
cd Ghost- change into the project folder
npm install -g grunt-cli- to make it possible to run grunt commands (see developer tips for more info on Grunt)
npm install- you need all the dependencies, so do not use the
--productionflag mentioned in user install guides
- 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
grunt init- updates bower dependencies, copies assets and compiles Handlebars templates
- If you're going to run in production mode, you also need to run
npm start- starts Ghost or
grunt devwill start it in watch mode
If something goes wrong, please see the troubleshooting tips below.
Looking for something to work on?
If you're interested in contributing to Ghost and don't know where to start, here's a few tips:
- The beginner label indicates issues which should be suitable for someone new to the Ghost codebase
- The help wanted label highlights issues that need a champion
- The roadmap wiki page has details of how we use milestones to prioritise issues
If you're still stuck, please come join us in slack and let us know what you're interested in!
Whilst developing, you can take advantage of the Grunt toolkit to automatically compile assets, such as handlebars templates, styles and ember scripts. Some useful commands include:
grunt dev=> Watch for changes and automatically rebuild assets
grunt prod=> Build assets for the production environment
grunt validate=> Run the linting and test suite
Addresses for development:
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
grunt init- will fetch bower dependencies and recompile handlebars templates for the admin
- 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. Do NOT use this branch for a production site.
- stable contains the latest release of Ghost. This branch may be used in production.
- gh-pages contains The Ghost Guide our developer documentation.
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.
Ghost doesn't do anything - I get a blank screen
Sounds like you probably didn't run the right grunt command for building assets. You may need to run
grunt init and if using production mode,
grunt prod as well.
node-gyp errors or 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.