Developing for Apache Phoenix

Below are the steps necessary to setup your development environment so that you may contribute to Apache Phoenix.

Getting Started

  1. Review the How to Contribute documentation.
  2. Sign up for a github.com account if you don’t have one.
  3. Go to the Phoenix Github Repository and create a fork of the repository which will create repository {username}/phoenix.
  4. Setup git locally.
  5. Make sure you have a jdk (Phoenix requires JDK 7).
  6. Make sure you have maven 3+ installed.

  7. Add the following to you .bashrc or equivalent to make sure maven and java are configured to run from command line correctly.

    export JAVA_HOME={path to jdk}
export JDK_HOME={path to jdk}
export M2_HOME={patch to maven}
export PATH=$M2_HOME/bin:$PATH

Other Phoenix Subprojects

The instructions here are for the main Phoenix project. For the other subprojects, use the corresponding repository and JIRA project.

The Eclipse and IntelliJ setup instructions may not necessarily work well for the other projects.

Setup Local Git Repository

Note that you may find it easier to clone from the IDE of your choosing as it may speed things up for you especially with Intellij

  1. Create a local clone of your new forked repository

    git clone https://github.com/{username}/phoenix.git

  2. Configure your local repository to be able to sync with the apache/phoenix repository

    cd {repository}
git remote add upstream https://github.com/apache/phoenix.git
  3. Setup your development environment

For Eclipse IDE for Java Developers (Luna)

  1. Download Eclipse
    • You will want ‘Eclipse IDE for Java Developers’ unless you want to install the following tools by hand
  2. Configure Eclipse to handle Maven Issues appropriately so you don’t see unnecessary errors.
    • Window -> Preferences -> Maven -> Errors/Warnings
    • Choose Ignore option for ‘Plugin execution not covered by lifecycle configuation’ -> Ok
  3. Add a the local git repository to Eclipse
    • Window -> Show View -> Other… -> Git | Git Repositories -> Ok
    • Click ‘Add an existing local Git Repository to this view’
    • Search for appropriate git repository
    • Finish
  4. Import Maven Projects
    • File -> Import -> Maven -> Existing Maven Projects
    • Choose Root directory where phoenix git repository is located
    • Select All
    • Finish
  5. Generate Lexer and Parser Files
    • Select phoenix-core project
    • Run -> Run As -> Maven generate-sources
  6. Make sure you are setup to develop now.
    • Open IndexUtilTest.Java
    • Run -> Run As -> JUnit Test

Get Settings and Preferences Correct

  1. Import General Preferences
    • File -> Import… -> General -> Preferences
    • From - {repository}/dev/eclipse_prefs_phoenix.epf
    • Import All
    • Finish
  2. Import Code Templates
    • Window -> Preferences -> Java -> Code Style -> Code Templates -> Import…
    • Navigate to {repository}/dev/PhoenixCodeTemplate.xml -> Ok
  3. Import Formatter
    • Window -> Preferences -> Java -> Code Style -> Formatter-> Import…
    • Navigate to {repository}/dev/PhoenixCodeTemplate.xml -> Ok
  4. Import correct import order settings
    • Window -> Preferences -> Java -> Code Style -> Organize Imports -> Import…
    • Navigate to {repository}/dev/phoenix.importorder -> Ok
  5. Make sure you use space for tabs
    • Window -> Preferences -> General -> Editors -> Text Editors
    • Select ‘Insert Spaces for tabs’ -> Ok

Connecting to Jira

  1. Install Connector for Jira
  2. Add Task Repository
    • Window -> Show View -> Mylyn -> Task Repositories -> Add Task Repository
    • JIRA -> Next -> Server - https://issues.apache.org/jira -> Validate Settings
    • Finish
  3. Add Filter Of All JIRAs assigned to you
    • Right Click on Repository You added -> New Query… -> Predefined Filter
    • Select Phoenix Project -> Select Assigned to me
    • Finish

Commit

  1. Commit Changes and Push to Github with appropriate Message
    • CTRL-# -> Set Commit message to include jira number at beginning PHOENIX-####
    • Commit and Push

For Intellij

If you don’t have a local git repository setup

This will automatically create the local clone of your repository for you. You will still want to add the remote upstream repository from above afterwards.

  1. Clone Github project and Import Maven Projects to IDE
  2. Generate Parser and Lexer Files
    • Maven Projects -> Phoenix Core -> Lifecycle -> compile
  3. Compile Project
    • Build -> Make Project
  4. Make sure you are setup to develop now.
    • Open IndexUtilTest.Java -> Run -> Run IndexUtilTest

If you already have a local git repository setup

  1. Import Projects
    • Import Project
    • Select Directory of your local repository -> Next
    • Import project from external model -> Maven -> Next
    • Select ‘Import Maven project automatically’
    • Select ‘Create IntelliJ IDEA modules for aggregator projects’
    • Select ‘Keep source and test folders on reimport’
    • Select ‘Exclude build directory’
    • Select ‘Use Maven output directories’ -> Next
    • Select maven-3 -> Next
    • Next a whole bunch
  2. Generate Parser and Lexer Files
    • Maven Projects -> Phoenix Core -> Lifecycle -> compile
  3. Compile Project
    • Build -> Make Project
  4. Make sure you are setup to develop now.
    • Open IndexUtilTest.Java -> Run -> Run IndexUtilTest

Get Settings and Preferences Correct

  1. Import Settings from eclipse profile
    • File -> Settings -> Editor -> Code Style -> Java
    • Set From… -> Import… -> Eclipse XML Profile -> {repository}/dev/PhoenixCodeTemplate.xml

Connecting to Jira

  1. Create Connection to Apache Jira
    • Tools -> Tasks and Contexts -> Configure Servers -> + -> Jira ->
    • Server Url: ‘https://issues.apache.org/jira’
    • Query: ‘project=Phoenix and …’
  2. Switch Easily between Tasks
    • Tools-> Tasks and Contexts -> Open Task->PHOENIX-####
    • Select Create branch PHOENIX-#### from master->OK

Commit

  1. Commit Changes and Push to Github with appropriate Message
    • VCS -> Commit -> Set Commit message to include jira number PHOENIX-####
    • Commit and Push

Contributing finished work

Create pull request

  1. Review the How to Contribute documentation.
  2. Navigate to branch - https://github.com/{username}/phoenix/tree/{branchname}
  3. Click Pull Request
  4. Confirm that you see apache:master … {username}:{branchname}
  5. Make sure Title of pull request has the jira name at beginning PHOENIX-{####}
  6. Click create pull request

Back to top

Copyright ©2024 Apache Software Foundation. All Rights Reserved.