Contributor Getting Started Guide

 

Welcome to the Contributor's Getting Started Guide. The following is a compendium of the most significant links related to the development of RichFaces. This guide will help you getting your development environment ready for RichFaces development. You will learn the structure of the  repository as well as get a brief status of the project.

 

If you are looking for ways to contribute to the project other than code contributions, or for details on how to keep your finger on the "pulse" of the project:

 

Refer to our more general Contributing to RichFaces section.

 

Component Development and Submitting a Patch

 

What follows is an outline of the steps you have to take to checkout the RichFaces code, make your change, and submit the pull request to contribute back your change.

 

Prepping your accounts & environment

 

  1. Create appropriate accounts
  2. Fork github repository for the appropraite RichFaces module
  3. Clone your newly forked copy into your local workspace
    • > git clone git@github.com:[your github username]/sandbox.git
      Cloning into sandbox...
      remote: Counting objects: 4743, done.
      remote: Compressing objects: 100% (2116/2116), done.
      remote: Total 4743 (delta 1597), reused 4663 (delta 1517)
      Receiving objects: 100% (4743/4743), 1.82 MiB | 434 KiB/s, done.
      Resolving deltas: 100% (1597/1597), done.
      
    • To checkout and build the RichFaces project in it's entirety (all the modules), refer to the guide:How to Build RichFaces 4.x
  4. Add a remote reference to upstream, for pulling in changes as they are committed upstream
    • git remote add upstream git://github.com/richfaces/sandbox.git
  5. Prep your build environment
    • While you can build applications using the RichFaces artifacts published to maven central, you will need to setup your local maven build to point to the JBoss Nexus repository.
    • Refer to the guide How to Build RichFaces 4.x for instruction on setting up your build environment
  6. Build using maven
    • With your build enviroment prepared, you can now build your checked-out module:
      mvn clean install

 

Identify and communicate your intentions, then submit the patch!

 

Ok, now we have our environment prepared, the next step is to share our intentions for a fix/feature with the rest of the community

 

  1. Create an issue to track the fix/feature in our issue tracker
    • if the issue already exists, add a comment indicating your intention to work on it
    • For more details on the differant ways in which we use our issue tracker, see the guide: RichFaces Jira Usage Guide
  2. Facing a complex issue? Not sure the best way to proceed?
    • Get in touch with the Richfaces developer community to discuss your issue via:
      1. Comments in the issue in the issue tracker
      2. Start a discussion in the developer forum
      3. IRC
        • Join us for our weekly team meetings in IRC
        • Alternatively join the #richfaces IRC channel at any time for an ad-hoc discussion
    • We'll be more than happy to discuss the nature of your issue, and help guide you to a solution via any channel
  3. Create your patch, either:
    1. dierectly in your clone of the develop branch
      • this is an appropriate approach for quick-fixes
    2. in a new branch (within your fork)
      • this approach is advantageous when developing longer-iteration features/fixes
      • the core dev team uses git flow to manage our git branches, but that is not a requirement for contributing
  4. Test your patch
    • Run it locally
    • Write a unit test (a difficult process at the moment, we'll update this space with an appropriate howto when it's ready)
  5. Submit a pull request

 

Thanks for taking the time to contribute back to the project - we look forward to reviewing and processing your pull requests!