Git workflow

Full details Forking Workflow

Other interesting reading:

• GitHub Patterns
• Git Workflow

Quick Summary

Each developer should fork the private core Ghost repo into a private repo of their own and clone this as their local repo. Remember to add the main repo as a remote:

git remote add upstream git@github.com:TryGhost/Ghost.git

Once a change is ready to be added back to the core repo, a pull request should be issued. For the immediate future only, all pull requests will be handled by Hannah Wolfe.

Be sure to pull from the core repo regularly :)

Notes on writing good commit messages

• The first line of your commit message should be a short (80 chars) public description of what you have achieved with the commit. This is what appears in the change log.
• Leave a blank line after the first line
• The 3rd line should reference the issue with issue #000 if you just want to mention an issue or closes #000 if your commit closes an issue.
• Use bullet points on the following lines to explain what your changes achieve and in particular why you've used your approach

E.g.

Show message and don't start on unsupported node versions

closes #292
- added engines and enginestrict properties to package.json
- these provide warnings / errors when installing through npm
- added our own check using this info on start, throws a useful error and stops the app if the node version is not supported
- also switched sqlite3 to the latest version and checked it works with various node versions

See the original

Submitting Pull Requests

The easier it is for me to merge a PR, the faster I'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 confortable 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 ones are 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.

Submit!

Now that your history is nice and clean, fetch the latest updates from upstream. Assuming you never touched the master branch, do:

> git checkout master
> git pull upstream master

Then rebase your branch/changes on top of master:

> git checkout my-branch-name
> git rebase master

And finally push your work to your fork:

> git push -u origin my-branch-name

GitHub will offer to create a pull-request from newly created branches automatically.

Now submit your PR with all the latest changes from master and a nice clean history with useful commit messages. Finish up by adding a description to the PR which details any interesting changes, any tools or libraries you've added and warnings for any breaking changes.

Updating a Pull Request

If your PR has fallen behind and can't be merge cleanly, just re-do the steps above (pull from master, rebase your branch), then force push to your branch using git push -f origin my-feature-branch. This will update the PR commits. Of course, never force push to any branch you have shared with others.

Thanks!

Note: - this is my way of getting everything neat and tidy, you may have another, as long as the result is nice easy-to-merge PRs.

What I do:

I will read through your code, checkout your PR, merge master if it's out of date and run basic sanity / regression tests on the code & re-run grunt validate if needed. If you haven't followed the above steps, I will do my best to achieve the same results. If you have, I can just press the nice green button on github.

Working with issues

Feel free to pick up any issue which is not assigned. Please leave a comment on the issue to say you wish to pick it up, and it will get assigned to you.