288 lines
13 KiB
Markdown
288 lines
13 KiB
Markdown
# 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.
|
|
|
|
There are lots and lots of ways to get involved, this document covers:
|
|
|
|
* [raising issues](#raising-issues)
|
|
* [bug reports](#bugs)
|
|
* [feature requests](#features)
|
|
* [change requests](#changes)
|
|
* [working on Ghost core](#core)
|
|
* [submitting pull requests](#pull-requests)
|
|
* [testing and quality assurance](#testing)
|
|
* [writing documentation](#documentation)
|
|
* [translation](#translation)
|
|
|
|
|
|
<a name="raising-issues"></a>
|
|
## Reporting An Issue
|
|
|
|
If you're about 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.
|
|
|
|
The GitHub issue tracker is the preferred channel for [bug reports](#bugs),
|
|
[feature requests](#features), [change requests](#changes) and [submitting pull
|
|
requests](#pull-requests), but please respect the following restrictions:
|
|
|
|
* 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** use the issue tracker for personal support requests (use
|
|
[the forum](http://ghost.org/forum) or IRC - #ghost on freenode).
|
|
|
|
* Please **do not** derail or troll issues. Keep the discussion on topic and respect the opinions of others.
|
|
|
|
<a name="bugs"></a>
|
|
### Bug Reports
|
|
|
|
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:
|
|
|
|
1. **Use the GitHub issue search** — check if the issue has already been
|
|
reported.
|
|
|
|
2. **Check if the issue has been fixed** — try to reproduce it using the
|
|
latest `master` or look for [closed issues in the current milestone](https://github.com/TryGhost/Ghost/issues?labels=&milestone=3&page=1&state=closed).
|
|
|
|
3. **Isolate the problem** — ideally create a [reduced test
|
|
case](http://css-tricks.com/6263-reduced-test-cases/) and a live example.
|
|
|
|
4. **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](http://www.cockos.com/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.
|
|
|
|
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](https://github.com/TryGhost/Ghost/issues/413)
|
|
|
|
Template:
|
|
|
|
> Short and descriptive example bug report title
|
|
>
|
|
> ### Issue Summary
|
|
>
|
|
> A summary of the issue and the browser/OS environment in which it occurs. If
|
|
> suitable, include the steps required to reproduce the bug.
|
|
>
|
|
> ### Steps to Reproduce
|
|
>
|
|
> 1. This is the first step
|
|
> 2. This is the second step
|
|
> 3. Further steps, etc.
|
|
>
|
|
> Any other information you want to share that is relevant to the issue being
|
|
> reported. Especially, why do you consider this to be a bug? What do you expect to happen instead?
|
|
>
|
|
> ### Technical details:
|
|
>
|
|
> * Ghost Version: master (latest commit: 590ba48988b51b9c5e8d99afbb84c997436d7f21)
|
|
> * Client OS: Mac OS X 10.8.4
|
|
> * Server OS: CentOS 6.4
|
|
> * Node Version: 0.10.16
|
|
> * Browser: Chrome 29.0.1547.57
|
|
|
|
|
|
<a name="features"></a>
|
|
### Feature Requests
|
|
|
|
Feature requests are welcome. Before you submit one be sure to have:
|
|
|
|
1. Read the [Roadmap](https://github.com/TryGhost/Ghost/wiki/Roadmap) and
|
|
[Planned Features](https://github.com/TryGhost/Ghost/wiki/Planned-Features) listing, **use the GitHub search** and
|
|
check the feature hasn't already been requested.
|
|
2. Take a moment to think about whether your idea fits with the scope and aims of the project, or if it might
|
|
better fit being an app/plugin.
|
|
3. Remember, it's up to *you* to make a strong case to convince the project's leaders of the merits of this
|
|
feature. Please provide as much detail and context as possible, this means explaining the use case and why it is
|
|
likely to be common.
|
|
4. Clearly indicate whether this is a feature request for Ghost admin, or for themes or apps.
|
|
|
|
|
|
<a name="changes"></a>
|
|
### Change Requests
|
|
|
|
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:
|
|
|
|
1. **Use the GitHub search** and check someone else didn't get there first
|
|
2. Take a moment to think about the best way to make a case for, and explain what you're thinking. Are you sure
|
|
this shouldn't really be a [bug report](#bug-reports) or a [feature request](#feature-requests)? Is it really one
|
|
idea or is it many? What's the context? What problem are you solving? Why is what you are suggesting better than
|
|
what's already there? Does it fit with the Roadmap?
|
|
|
|
|
|
<a name="pull-requests"></a>
|
|
### Submitting Pull Requests
|
|
|
|
Pull requests are awesome. To make sure yours is accepted as quickly as possible, you should be sure to have read
|
|
all the guidelines on:
|
|
|
|
* [code standards](https://github.com/TryGhost/Ghost/wiki/Code-standards)
|
|
* [commit messages](https://github.com/TryGhost/Ghost/wiki/Git-workflow#commit-messages)
|
|
* [cleaning-up history](https://github.com/TryGhost/Ghost/wiki/Git-workflow#clean-up-history)
|
|
* [not breaking the build](https://github.com/TryGhost/Ghost/wiki/Git-workflow#check-it-passes-the-tests)
|
|
|
|
##### 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](https://github.com/TryGhost/Ghost/wiki/Git-Workflow) for Ghost.
|
|
|
|
|
|
<a name="testing"></a>
|
|
### 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](https://github.com/TryGhost/Ghost/wiki/QA-Documentation) on the wiki.
|
|
|
|
Essentially though, [check out the latest master](#core), take it for a spin, and if you find anything odd, please
|
|
follow the [bug report guidelines](#bug-reports) and let us know!
|
|
|
|
#### Checking out a Pull Request
|
|
|
|
These are some [excellent instructions](https://gist.github.com/piscisaureus/3342247) on configuring your GitHub
|
|
repository to allow you to checkout pull requests in the same way as branches:
|
|
<https://gist.github.com/piscisaureus/3342247>.
|
|
|
|
|
|
<a name="documentation"></a>
|
|
### Documentation
|
|
|
|
Ghost's main documentation can be found at [docs.ghost.org](http://docs.ghost.org).
|
|
|
|
The documentation is generated using jekyll, all of the docs are on the gh-pages branch on the GitHub repository.
|
|
You can clone the repo, checkout the gh-pages branch, and submit pull requests following
|
|
the [pull-request](#pull-requests) guidelines.
|
|
|
|
|
|
<a name="translation"></a>
|
|
### Translation
|
|
|
|
Full documentation on contributing translations can be found at <http://docs.ghost.org/translations>
|
|
|
|
|
|
|
|
<a name="core"></a>
|
|
## Working on Ghost Core
|
|
|
|
**Note:** It is recommended that you use the [Ghost-Vagrant](https://github.com/TryGhost/Ghost-Vagrant) setup for
|
|
developing Ghost.
|
|
|
|
**Pre-requisites:**
|
|
|
|
* Node 0.10.x
|
|
* ruby and the gems 'sass' and 'bourbon' - you can use `bundle install` to install the gems
|
|
* for running functional tests: phantomjs 1.9.x and casperjs 1.1.x
|
|
([instructions](https://github.com/TryGhost/Ghost/wiki/Functional-testing-with-PhantomJS-and-CasperJS))
|
|
* for building docs: python and pygments
|
|
|
|
|
|
### Installation / Setup Instructions
|
|
|
|
1. Check you have the pre-requisites listed above!
|
|
1. Clone the git repo
|
|
1. cd into the project folder
|
|
1. Run `git submodule update --init`
|
|
1. Run `npm install -g grunt-cli`
|
|
1. 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
|
|
1. Run `grunt init` from the root - this generates the Bourbon directory, compiles SASS and compiles Handlebars
|
|
templates
|
|
1. Run `npm start` from the root to start the server.
|
|
|
|
If something goes wrong, please see the
|
|
[troubleshooting tips](https://github.com/TryGhost/Ghost/blob/master/CONTRIBUTING.md#troubleshooting--faq) below.
|
|
|
|
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](https://github.com/TryGhost/Ghost/wiki/Grunt-Toolkit).
|
|
|
|
### 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](https://github.com/TryGhost/Ghost)** is the bleeding edge development branch. All work on the next
|
|
release is here.
|
|
- **[gh-pages](http://tryghost.github.io/Ghost)** is The Ghost Guide documentation for Getting Started with 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](http://incident57.com/codekit/) (Paid/Mac)
|
|
& [Scout](http://mhs.github.io/scout-app/) (Free/Mac/PC).
|
|
You will need to have Ruby installed, as well as having run `gem install sass && gem install bourbon`.
|
|
|
|
## Grunt Toolkit
|
|
|
|
Ghost uses Grunt heavily to automate useful tasks such as building assets, testing, live reloading/watching etc etc
|
|
|
|
[Grunt Toolkit docs](https://github.com/TryGhost/Ghost/wiki/Grunt-Toolkit) 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`.
|
|
|
|
### 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](https://github.com/developmentseed/node-sqlite3/wiki/Binaries).
|
|
|
|
|
|
## 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.
|