Whether you've got a bugfix, documentation update, or new feature for us, these are the steps to follow to contribute code back into the main joind.in repo.
1. Get the latest code from Github
You'll need to understand a little bit about how git and gihub work before this step (if you need an introduction guide, Github has a good one you can learn from). In simple terms, log in to github, visit the joind.in project page, and click the "fork" button to create your own copy of the repo. You will push your changes to this new repo under your own github account, and we will pull changes into the main repo from there.
For the sake of the rest of the examples in this guide, we're going to assume your Github username is "arthurdent" and use that in our examples.
Now, we want to grab the latest from this newly created repository and pull it down to your local machine. Getting the latest code from your repo is simple, just clone it:
git clone https://github.com/arthurdent/joind.in.git --recursive cd joind.in
This will give you a directory called "joind.in" on your local machine with the latest checkout from your fork of the main Joind.in repo. Note: this is not a direct reference to the main Joind.in repo. When you make changes in your fork, you'll need to let us know about it so we can pull it over....but that's later in the process.
2. Add a remote for the main Joind.in repo
One thing you'll need to do to make things easier to integrate and keep up to date in your fork is to add the main Joind.in repo as a remote reference. This way you can fetch the latest code from the production version and integrate it. So, here's how to set that up:
git remote add upstream https://github.com/joindin/joind.in.git git remote (this will list out your remotes, showing the new one we added)
Then, when you need to pull the latest from the main Joind.in repo, you just fetch and merge the master branch:
git fetch upstream git merge upstream/master
You can also use git pull upstream master if you want it all in one step.
3. Making a branch for your changes
When adding features or bug fixes, please create a separate branch for each changeset you want us to pull in, either with the issue number in the branch name or with an indication of what the feature is. For more detailed instructions, read the "Working with Zend Framework" section on this page - we use the same conventions developed by Zend Framework so we refer to their docs rather than maintaining our own! To create the branch, do something like this:
git branch (lists your current branches) git branch my_new_code (makes a new branch called my_new_code) git checkout my_new_code
If you're working on an issue in the Issues list for the main Joind.in repo, use the naming convention "joindin-[issue-num]" for your branch name to help us keep track of what your patch actually fixes
4. Database Patches
Database patching is now handled in the API repository, see the README of that project for more information. If you are using Vagrant this is probably done automatically for you; refer to the README of the joind.in project to see if you need to complete this step.
4. Push your code and make a pull request
When you have finished making your changes, you'll need to push up your changes to your fork so we can grab them. With them all committed, push them:
git push origin my_new_code
This pushes everything in that branch up. Then you can go back to your forked Joind.in github page and issue a pull request from there. Tell us what you want us to merge and what it does/fixes, and one of us will pick it up.
That lets us know that there's something new from you that needs to be pulled in. We'll review it and get back to you about it if we have any questions. Otherwise, we'll integrate it and let you know when it's in!
Minimum PHP Version
Please be aware that the productions servers currently run PHP 5.5.x, and all patches should be created with this version in mind.
Hope this guide helps you get started in contributing to the Joind.in project! If you still have questions, don't hesitate to send an email over to email@example.com and we'll get back to you. You can also grab us on IRC - we're in #joind.in on freenode