...
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. |
...
Your changes need to be reviewed by a iota committer. Therefore, you need to create a pull request for your private repository.
The iota Automated Tests are triggered to run on every pull request. These tests take 1-2 hours to run. Shorter tests run if you've changed only documentation or the web site. Please refer to Automated Tests for information about how to check the outcome of these tests.
...
You should have a basic understanding of how iota is developed at this point. Where you go next depends on what areas you intend to contribute to:
- Create Build Environment: iota 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 iota source or test code. It’s not strictly needed if you intend to work on the iota documentation or web site; you can build these components without the complete iota Build Environment. Refer to Modify Documentation or Modify Web Site.
Build Source: You can build the iota source once the Build Environment has been created. Several options are available, including the capability to build the iota binaries.
Note You MUST create the Build Environment before Building the Source.
Create Test Environment: You need to set up the iota test environment in order to run the different iota test libraries. You need to set up an Hadoop environment to test iota. iota 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 iota binary or if you working on the Documentation and/or Web Site.
Modify Documentation: You can modify the iota documentation without creating the iota Build Environment or iota Test Environment. Typically, contributors working on the iota code also modify the iota Documentation when making changes.
Modify Web Site: You can modify the iota web site without creating the iota Build Environment or iota Test Environment.
Excerpt
Documents a basic overview of how we develop iota.
Table of Contents | ||||
---|---|---|---|---|
|
...
Working in Git
Install Git Tools
You use git to make changes to the iota 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 iota Source Tree
You download the iota source tree once the git tools have been installed.
Fork iota Repository
You create a private fork of iota on https://github.com/apache/incubator-iota. 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 iotadeveloper
to represent <your-git-id>
.
Clone iota Repository
Use the git shell to perform this task.
Code Block | ||||
---|---|---|---|---|
| ||||
# Move to the directory where you want to install the iota source code.
cd mysource
# Clone the iota source code
git clone git://git.apache.org/incubator-iota.git
# Change to the iota source-tree directory
cd incubator-iota
# Register your fork as a remote branch
git remote add iotadeveloper_fork git@github.com:iotadeveloper/incubator-iota |
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 iota source tree. Typically, we name the branches after the Jira we are working on. In this example, the Jira is: iota-1507.
Code Block | ||||
---|---|---|---|---|
| ||||
# Ensure that you have the latest changes
git fetch --all
# Checkout source
git checkout -b iota-1507 origin/master # or origin/releaseX.Y for a release patch |
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 iotadeveloper_fork HEAD
# Push changes to your private fork
git push iotadeveloper_fork iota-1507 |
Create Pull Request
Your changes need to be reviewed by a iota committer. Therefore, you need to create a pull request for your private repository.
The iota Automated Tests are triggered to run on every pull request. These tests take 1-2 hours to run. Shorter tests run if you've changed only documentation or the web site. 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-iota.
- 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 Command Line (with Hub extension)
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: [iota-1507] Explanation of the changes you made.
Review Comments
The pull request gets reviewed by the committers and other contributors. Once you get a consensus, the committer merges your changes into the target incubator-iota 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 iota-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 iotadeveloper_fork iota-1507
Info |
---|
The |
Warning |
---|
Do not use the |
Resolve Merge Conflicts
Sometimes someone else's changes reach the target branch (e.g., master) before yours and has a merge conflict with your changes. Github will flag that situation in the status of your pull request. Before your changes can be merged, you must resolve conflicts in your pull request. This is the same process as above, making code changes, except that a merge command is done to create the changes.
Using the prior example:
- Check out the code:
git checkout iota-1507
- git fetch origin
- git merge origin/master
- Resolve conflicts.
- 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 iotadeveloper_fork iota-1507
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 iota.
...
Where To Go From Here
You should have a basic understanding of how iota is developed at this point. Where you go next depends on what areas you intend to contribute to:
- Create Build Environment: iota 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 iota source or test code. It’s not strictly needed if you intend to work on the iota documentation or web site; you can build these components without the complete iota Build Environment. Refer to Modify Documentation or Modify Web Site.
Build Source: You can build the iota source once the Build Environment has been created. Several options are available, including the capability to build the iota binaries.
Note You MUST create the Build Environment before Building the Source.
Create Test Environment: You need to set up the iota test environment in order to run the different iota test libraries. You need to set up an Hadoop environment to test iota. iota 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 iota binary or if you working on the Documentation and/or Web Site.
Modify Documentation: You can modify the iota documentation without creating the iota Build Environment or iota Test Environment. Typically, contributors working on the iota code also modify the iota Documentation when making changes.
Modify Web Site: You can modify the iota web site without creating the iota Build Environment or iota Test Environment.