Table of Contents |
---|
You need to do the following to get started:
- Contributor Registration: Sign up with the tools used to develop Trafodion.
- Tools and Guidelines: Familiarize yourself with the tools and guidelines used to develop Trafodion.
- Development Workflow: Familiarize yourself with how to work with git, make changes, commit changes, and generate pull requests.
- Next Steps: Decide where to go next in this guide depending on your intended contribution.
Anchor | ||||
---|---|---|---|---|
|
Contributor Registration
You need to register as a Trafodion contributor before you can help us develop Trafodion. Please perform the following registration actions:
Area | Notes | URL |
---|---|---|
Individual Contributor License Agreement (ICLA) | You should sign the ICLA before contributing content to the Trafodion source tree. (Required to become a committer.) | ICLA Agreement Approval Process |
Source Control | You must have a git account in order to contribute to the Trafodion source. If you haven’t already done so, please join git. | Git Sign-up |
Defect Tracking | In order to have certain permissions, including assigning issues to yourself, you need to be a Contributor in the project. Be sure to sign up for a JIRA account if you don’t have one. | Jira Signup |
Please send an e-mail to the Trafodion development list with the approved ICLA attached. Include your git and Jira IDs. Wait for the response and then you’re ready to help us develop Trafodion. You will be added (by designated space admins) to:
- The Trafodion Confluence Contributors group, so that you can add new and edit existing wiki pages.
- The Trafodion JIRA Contributors group, so that you can assign yourself to any open issue in order to bring it further to resolution and/or closure.
Anchor | ||||
---|---|---|---|---|
|
Tools and Guidelines
Area | Tool | Notes | Location |
---|---|---|---|
Trafodion Architecture | Document | Please review the Trafodion architecture to ensure that you understand how the different components related to each other. | Trafodion Architecture |
Defect Tracking | Jira | View all the Trafodion defects and enhancements requests in the Jira system hosted by Apache. | Trafodion Jiras |
Defect Management | Document | Please read about our approach to defect management. Mostly, any changes you’ll make will be in response to a defect reported in Jira. | Defect Management |
Git Tools | git | Most of the Trafodion development is done on Linux. Development of the web site and/or documentation can successfully be done on Windows. | Install Git Tools |
Code Repository | git | The full Trafodion source tree can be retrieved from either of these repositories. | Apache Repository GitHub Mirror |
Code Organization | Document | If you intend to work on the Trafodion code, then please familiarize yourself with the code organization. | Code Organization |
C++ Coding Guidelines | Document | Please read the coding guidelines for the Trafodion C++ code before making changes. | C++ Coding Guidelines |
Debugging Tips | Document | Documented tips describing how to debug your code in unit testing. | Debugging Tips |
Testing | Document | Trafodion has a rich set of test suites for each of its components. You’ll need to run the tests before submitting a code change for review. | How to Test |
Code Reviews | git | We use GitHub pull-requests for code review. All of the activity on GitHub is captured in ASF JIRA and/or ASF project mail archives by ASF INFRA team automation. In this way, we do not depend on GitHub for accurate history of where contributions come from. Each pull-request title should start with a JIRA ID in brackets, so that activity can be logged to the correct JIRA issue. Regardless of the title, the pull-request activity is also logged to the Code-Review Mail List. | Current Pull Requests |
Anchor | ||||
---|---|---|---|---|
|
Development Workflow
The following provides a basic overview of how we develop Trafodion.
Install Git Tools
You use git to make changes to the Trafodion code, tests, documentation, and web site:
- Download the appropriate tool version; Linux or Windows: http://git-scm.com/downloads.
- Set up your git environment: GitHub Documentation
- Ensure that you register your ssh keys.
Info | ||
---|---|---|
| ||
For future reference, the git commands used below are summarized in Git Cheatsheet in the How-To chapter. |
Download Trafodion Source Tree
You download the Trafodion source tree once the git tools have been installed.
Fork Trafodion Repository
You create a private fork of Trafodion on https://github.com/apache/incubator-trafodion. Use the fork button top-right on the page to create your fork, which will be named <your-git-id>_fork
.
The following examples use trafdeveloper
to represent <your-git-id>
.
Clone Trafodion Repository
Use the git shell to perform this task.
Code Block | ||||
---|---|---|---|---|
| ||||
# Move to the directory where you want to install the Trafodion source code. cd mysource # Clone the Trafodion source code git clone git://git.apache.org/incubator-trafodion.git # Register your fork as a remote branch git remote add trafdeveloper_fork git@github.com:trafdeveloper/incubator-trafodion |
At this point, you’ve finished all preparation steps. Now, you can start making changes.
Make Changes
Create Task Branch
You create a task branch to make changes to the Trafodion source tree. Typically, we name the branches after the Jira we are working on. In this example, the Jira is: TRAFODION-1507.
Code Block | ||||
---|---|---|---|---|
| ||||
# Ensure that you have the latest changes git fetch --all # Checkout source git checkout -b TRAFODION-1507 origin/master |
Change Recipes
How to make changes depends on what part of the source tree you are working on. Please refer to the following chapters:
Change Type | Refer To... |
---|---|
Code | Modify Code |
QA Tests | Modify Tests |
Documentation | Modify Documentation |
Web Site | Modify Web Site |
Commit Changes
Note | ||
---|---|---|
| ||
If you’re making code changes, then ensure that you run the Regression Tests before committing changes. |
Perform the following steps to commit your changes.
Code Block | ||||
---|---|---|---|---|
| ||||
# Commit changes git commit -a # Dry-run check against main branch git push -n trafdeveloper_fork HEAD # Push changes to your private fork git push trafdeveloper_fork TRAFODION-1507 |
Create Pull Request
Your changes need to be reviewed by a Trafodion committer. Therefore, you need to create a pull request for your private repository.
The Trafodion Automated Tests are triggered to run on every pull request. These tests take several hours to run. We always run these tests even if you’ve changed documentation or the web site to ensure that no inadvertent change to the rest of the source tree occurred as part of your changes. Please refer to Automated Tests for information about how to check the outcome of these tests.
Using GitHub Web Site (Preferred)
Do the following:
- Go to https://github.com/apache/incubator-trafodion.
- Click the green Create Pull Request button.
- Review changes one more time before clicking Create Pull Request.
Please refer to https://help.github.com/articles/creating-a-pull-request/ for more documentation.
Using Git Bash
Do the following:
Code Block | ||||
---|---|---|---|---|
| ||||
# Generate pull request git pull-request |
Ensure that you include the Jira ID at the beginning of the title in your pull request. For example: [TRAFODION-1507] Explanation of the changes you made.
Review Comments
The pull request gets reviewed by the committers and once you get a consensus, then the committer merges your changes into the main incubator-trafodion branch. Check your e-mail for comments.
Address Review Comments
Follow the GitHub conversation on your pull request (you should be automatically subscribed). Respond to questions and issues.
If you need to make additional changes, then do the following (the example below uses a sample Jira ID):
- Check out the code:
git checkout TRAFODION-1507
- Make the requested changes.
- Run regression tests, if applicable.
- Commit the changes with appropriate change information:
git commit -a
- Push the changes back to your private git fork:
git push trafdeveloper_fork TRAFODION-1507
Info |
---|
The |
Warning |
---|
Do not use the |
Change Merge
If all is well, a committer will merge your change into the Apache repository, which is mirrored on GitHub. You may be asked to close out the JIRA or other follow up.
Your change is done. Thanks for your contribution to Trafodion.
Anchor | ||||
---|---|---|---|---|
|
Next Steps
You should have a basic understanding of how Trafodion is developed at this point. Where you go next depends on what areas you intend to contribute to:
- Create Build Environment: Trafodion requires a number of Linux packages and tools before you can build the code. This step is required if you intend to work on the Trafodion source or test code. It’s not strictly needed if you intend to work on the Trafodion documentation or web site; you can build these components without the complete Trafodion Build Environment. Refer to Modify Documentation or Modify Web Site.
Build Source: You can build the Trafodion source once the Build Environment has been created. Several options are available, including the capability to build the Trafodion binaries.
Note You MUST create the Build Environment before Building the Source.
Create Test Environment: You need to set up the Trafodion test environment in order to run the different Trafodion test libraries. You need to set up an Hadoop environment to test Trafodion. Trafodion includes scripts to create a small Hadoop environment, if needed.
Note You MUST create the Build Environment before creating the Test Environment.
This step is not necessary if you just want to build a Trafodion binary or if you working on the Documentation and/or Web Site.
Modify Documentation: You can modify the Trafodion documentation without creating the Trafodion Build Environment or Trafodion Test Environment. Typically, contributors working on the Trafodion code also modify the Trafodion Documentation when making changes.
Modify Web Site: You can modify the Trafodion web site without creating the Trafodion Build Environment or Trafodion Test Environment.