2011
06.20

Ok, I have to admit that the title is a little misleading…  This isn’t a traditional “Grails 101″ where you learn how to install the framework and create twitter, ha! This is instead an article about what it means to get started contributing back to the Grails community. I just started doing this a couple months ago, so I thought it would be interesting to blog about the steps required to do so for anyone else that wants to start contributing!

So, how do most people get started with Grails?  They go to grails.org and download the ZIP binary, right?  Sure, this is good, but if that’s all you do then you are kind of missing out.  I would argue that starting out with any new technology, the first thing you should do is build it from scratch!  Wait, what?  Why waste your time building from scratch?  The reason is you need to understand what’s happening under the hood to really become an expert so you can make modifications if needed for your application.  I’m certainly not an expert on Grails (yet!) but I have definitely increased my knowledge about the framework and become a better Grails developer by building Grails from source, examining the source code and contributing patches to the documentation!

So, let’s dive in!

  1. Login to GitHub (create an account if you don’t have one)
  2. Navigate to Grails-Core and Grails-Doc and fork both of them. You should now have your two forks similar to these Bobby Warner Grails-Core, & Bobby Warner Grails-Doc for your account
  3. Next you want to create your local copy (a clone in Git terms) and you can do this by executing these two commands:
    • git clone git@github.com:youraccount/grails-core.git
    • git clone git@github.com:youraccount/grails-doc.git
  4. There’s three sets of repositories now, the original ones at github.com/grails, your forks at github.com/youraccount and your local copies. We already have a reference from local to the GitHub forks, but we also want a reference from local to the originals so that we can pull in updates that are made by other users since we forked.
    • cd grails-core
    • git remote add upstream git://github.com/grails/grails-core.git
    • git fetch upstream
    • cd ../grails-doc
    • git remote add upstream git://github.com/grails/grails-doc.git
    • git fetch upstream
  5. Now we have our local repositories all set and it’s time to build them!
    • cd ../grails-core
    • ./gradlew install
    • cd ../grails-doc
    • ./gradlew docs  (Or  ./gradlew docs -Dgrails.home=../grails-core)
    • Set your $GRAILS_HOME to the grails-core directory
    • grails create-app newapp
  6. Now we’re rocking!  We have our own local copies of the Grails source-code and the documentation and are ready to start making our own modifications! We also created a new Grails application using our own local version of Grails we just compiled.
  7. Now it’s time to contribute something back to the community! First, we’ll have to find something to change. Then commit the change to our local repository and fork. Finally, we’ll open a pull request on the original Grails repository.  The example I’ll use just to explain was a simple change to the docs I made and opened a pull request for: https://github.com/grails/grails-doc/pull/46. You can see when clicking on that link that it is marked as “closed” status which means that someone on the core team (Burt Beckwith in this case) reviewed the pull request and committed to the master branch (my patch was “accepted” by the Grails team to the docs).  So, once you’ve found something you want to change, this is what you need to do:
    • git branch your-change-name
    • git checkout your-change-name
    • Edit the files you want to change 
    • git commit -a -m ‘Your Commit Message’
    • git push origin your-change-name
    • Then back on GitHub, click Pull Request to send it off for review! If it’s good, hopefully your pull request will be committed and if not, hopefully you’ll be given some comments about why not, ha!
  8. Lastly, you’ll want to make sure you keep your copies (remember there’s two, the GitHub fork and your local one) up to date with the original.
    • cd ../grails-core
    • git checkout master (if you made a branch here in step 7)
    • git fetch upstream
    • git merge upstream/master
    • git push origin master
    • ./gradlew install
    • cd ../grails-doc
    • git checkout master (if you made a branch here in step 7)
    • git fetch upstream
    • git merge upstream/master
    • git push origin master
    • ./gradlew docs  (Or  ./gradlew docs -Dgrails.home=../grails-core)
  9. Then just keep an eye on the GitHub pull request to see if it’s accepted!

Now that you’ve done a basic branch and pull request, it’s time to take a look at JIRA and see if you can tackle any open issues (or start opening your own!).  I personally haven’t solved too many issues yet other than some simple bug fixes, but hope to start contributing more in the future! 

I hope you enjoyed my “Getting Started With Grails” article.  Please let me know if you have any feedback or suggestions about the steps I outlined for getting started contributing back to Grails!

4 comments so far

Add Your Comment
  1. [...] Getting Started With Grails [...]

  2. Very good tutorial. Plain and simple (mainly due to the sole nature of git and github) but you are probably the first one to just put it together in one article. Good job and happy bug hunting!

  3. Bobby, nice tutorial. I’m starting with Grails and your tutorial helped me a lot contribute with the source. Any tips about doing all this in Eclipse? I’m trying to checkout a branch as project but I’m missing something. Thanks already.

  4. @Samuel, I use TextMate on Mac, so unfortunately not much help with Eclipse, sorry! Glad the article helped!

*

Switch to our mobile site