The best part about open source projects is you! Many hands make light work and at Ortus we love getting input from the many smart community members out there.  The first way you can help is to report bugs or enhancements in our ticket tracking system.  You can read our guide for that here:

http://blog.coldbox.org/blog/how-to-create-a-jira-account-and-enter-coldbox-tickets

The second thing you can do is to actually submit fixes yourself!  This may seem scary, but it's a pretty straight forward process once you've done it once.  We can never have too many people willing to help. Let's jump in and cover the steps it takes to submit some code to the ColdBox Platform.

Find Something To Do

We track out tickets for bugs and enhancements in JIRA.  Tickets are publicly browsable, but you can follow the steps in the link above to quickly sign up for an account that will allow you to vote, comment, and assign tickets.  The ColdBox project in our JIRA system is located here:

https://ortussolutions.atlassian.net/browse/COLDBOX

Feel free to enter tickets you'd like to see,but it's best to ask us to approve first before you spend time working on it so we can make sure everyone is on the same page. To mark a ticket as in progress drag it over to the "In Progress" column and drop it into the "Start Progress" box.  

Open the ticket by clicking the name and assign it to yourself with the "Assign to me" link in the upper right hand corner. 

Get a Git Client

Now that you know what you want to work on, you need a program to interact with GitHub. If you already have one or are a CLI ninja, you can skip this step.  Download and install GitHub For Desktop.

Get the Codes

Ok let's go get your own copy of the framework!  Load up the homepage on GitHub's website for the ColdBox Framework.

https://github.com/ColdBox/coldbox-platform

Now, click the "Fork" button in the upper right hand corner.  You'll need to be signed into your GitHub account for this.  Sign up for a free account if you don't already have one.

This will create a new copy of the original repository just for you.  When you're viewing your own repo, you will see something like this at the top:

Now, if you have GitHub For Desktop installed correctly, all you have to do is click the "Clone in Desktop" button on the bottom of the right-hand navbar.

GitHub For Desktop might ask you where to store the repo.  If you choose the default, it will go in a folder called "GitHub" in your documents.

Branch Out

The ColdBox Platform uses a common Git flow of having two main branches:

• master - This contains the last stable version of the code
• development - This contains the bleeding edge code as it is developed

We add all new code to the "development" branch and merge those changes into "master" when we're ready to publish a new release.  What you'll want to do is create a new branch off of the "development" branch that will live only in your fork and it will give you a nice place to store your changes. We recommend creating a branch for each ticket you submit a pull request for.  You can delete them later once we've pulled in the changes if you wish.

With the newly cloned repository open in GitHub For Desktop, checkout the "development" branch of code by selecting "development" from the drop down of branches in the top middle of the screen.

Great! Now click the tiny "branch" icon next to that same drop down to create a new branch that's based off the "development" branch.  Enter a descriptive name, ideally one that describes the change or simply has the ticket number.

Your new branch will be automatically checked out and it's name should show at the top of the window.  Congratulations, you're ready to code!

Make Your Changes

You can open up the folder that contains the code by right-clicking on the name of the repo in the left-hand side of the window and selecting "Open in Explorer".

You can use whatever editor you wish.  Just make sure everything works and you've removed any debugging code.  You can read the ColdBox development guidelines here:

http://wiki.coldbox.org/wiki/DevelopmentBestPractices.cfm

Don't Fear Commitment

After you've made your changes, click the text in the top right-hand corner of GitHub For Desktop that tells you that you have uncommitted changes.  This will pull up a list of changed files. Review what you're about to commit and make sure each file you intend to commit is checked.

Once you're ready to commit, enter a brief message in the Summary field at the bottom of the screen and click "Commit...".

We're Pulling for You

We're almost done!  Now that your changes have been committed to your local branch, it's time to create a pull request.  This notifies the owners of the original repository that you've made an improvement in your fork and you'd like them to "pull" it into the main repo.  Look for this "Pull Request" button that has appeared at the top of the GitHub For Desktop window.

This will open a window to finalize the details.  You will see where it says, "from <branch name> into <branch name>".  You MUST click to change the "into" branch to be "coldbox/development".  Since this branch name has the word "coldbox" in front of it, this is the upstream remote that points to the main ColdBox repository.  If you just send your pull request to your own "development" branch, we'll never get it!

You can add an additional message here if you like, but once the "into" branch has been set, you can finalize the deal with the "Send Pull Request" button.

All Done

That's it, your changes are now sent and the ColdBox team is automatically notified of your pull request.  

You can click the link to open your new pull request on github.com in your web browser.  There we can discuss the pull in the comments.  

Good work!  You've just contributed to the greater development community, helped out fellow programmerkind, and I'm pretty certain that somewhere, an angel just got his wings.  Let's review what you just did:

1. Found an approved ticket on an open source project
2. Forked the repo to create your own copy (You only need to do this once)
3. Created a branch off of "development"
4. Made your changes and committed them to that branch
5. Create a pull request back to the "development" branch on the main project.

If you have questions, please give a shout out on our Google Group.