Blog

Brad Wood

August 28, 2015

Spread the word


Share your thoughts

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.

Add Your Comment

(1)

Sep 04, 2015 12:11:14 UTC

by Tim Brown

If the pull request is for the docs this makes it super easy now to edit git books. https://www.gitbook.com/blog/releases/desktop-editor

Recent Entries

Into the Box 2024 Last Early Bird Days!

Into the Box 2024 Last Early Bird Days!

Time is ticking, with less than 60 days remaining until the excitement of Into the Box 2024 unfolds! Don't let this golden opportunity slip away; our exclusive Early Bird Pricing is here for a limited time only, available until March 31st. Why wait? Secure your seat now and take advantage of this steal!

Maria Jose Herrera
Maria Jose Herrera
March 20, 2024
Ortus February Newsletter 2024

Ortus February Newsletter 2024

Welcome to Ortus Solutions’ monthly roundup, where we're thrilled to showcase cutting-edge advancements, product updates, and exciting events! Join us as we delve into the latest innovations shaping the future of technology.

Maria Jose Herrera
Maria Jose Herrera
March 06, 2024
Unveiling the Future of CFML Development - 3rd Round of Sessions

Unveiling the Future of CFML Development - 3rd Round of Sessions

Welcome back to our journey into the future of CFML development! As excitement continues to build for Into the Box 2024, we're thrilled to bring you the latest updates on what promises to be a transformative event. Continuing our blog post series, let's delve deeper into the third wave of session releases and discover the key surprises awaiting attendees. Learn More

Maria Jose Herrera
Maria Jose Herrera
March 01, 2024