Table of Contents |
---|
There are 2 way how you can make contribution
Steps:
Then
You can start by cloning the Ignite GIT repo.
Info | ||
---|---|---|
| ||
git clone https: //git-wip-us .apache.org /repos/asf/incubator-ignite |
We use git as our version control system. To streamline the process of giving proper credit to the contributors when committing patches, we encourage contributors to submit patches generated using "git format-patch"
command. This has many benefits:
Long story short, it makes both the contributors' and committers' lives easier, so please generate your patches using git format-patch
.
We have the following requirements for patches:
We prefer that you use the following step-by-step instructions when developing with Ignite.
For example, if you are starting working on the feature IGNITE-9999.
## Get the repo
git clone https://github.com/apache/incubator-ignite.git
## Some development here with many commits at ignite-9999.
git commit -a -m 'ignite-9999: Intermediate commit 1';
...
git commit -a -m 'ignite-9999: Intermediate commit 100';
## Commit the last changes.
git commit -a -m 'ignite-9999: Implemented.';
## Making patch.
## There are a lot of changes at ignite-sprint-999 and we need to get it, resolve conflicts (if exists), rerun tests for ignite-9999.
git checkout master
git pull
git checkout ignite-9999
git merge master
## Run script to make patch. Patch will have all changes as one commit.
<ignite_home>/scripts/git-format-patch.sh
Note: it is strongly recommended to merge 'master' branch to your development branch, for example, every day (or after each commit).
Created patch-file should be attached to a JIRA ticket and the ticket status should be changed on Patch Available.
If you do everything correctly, then all necessary TC test builds will be triggered automatically in 3 minutes period, and a comment with triggered build information (test package names, TC build links) will be added to the JIRA.
Requirements (to auto triggering the test builds):
Info | ||||
---|---|---|---|---|
| ||||
Note: All TC test builds can be triggered manually via "Ignite/ -> Run All for patch" (by 'Jira number'). A comment will be added to the jira with all new triggered builds. |
Contributor patches have to be applied by next command.
git am -s <patch-file>
This command apply a patch file generated by 'git format-patch', stores information who created a patch and who applied a patch. So, it gives proper credit to the contributor and store an information who decide to take these changes.
If patch file has been created by scripts/git-format-patch.sh then a name of a patch-file contains a short hash revision of master branch revision against which patch has been created. Patch file template is
master_<hash>_ignite-<ticket-number>.patch
For example
master_b001525_ignite-9999.patch
Apache Way, Apache Con (Slides)
Info | ||
---|---|---|
| ||
The JIRA handling process outlined below should be followed in absolutely all cases, without exceptions, regardless of the ticket complexity. |
Info | ||
---|---|---|
| ||
New contributors should register account at https://issues.apache.org/jira/secure/Dashboard.jspa and send out email to project's dev list with request for contributors permissions. Committers should handle this request and grant contributor access to new community member. |
Tickets are picked up by community members from a pool of unassigned and unscheduled tickets after discussion on project's dev list. Assigning tickets to a version contributor helps others to understand what will be included in next release.
JIRA issues are grouped by fixVersion
field, which is an intended version of the product feature gets merged to. Everyone should make sure that after closing fixVersion
is set to a proper version that actually releases the changes made in scope of the ticket.
The following page contains information on upcoming releases (draft) Release Plan.
IN PROGRESS
state.If the changes implemented under the ticket require changes in user documentation, create a related documentation ticket (add "Documentation" to the Component field) and provide a reasonable amount of details in the ticket's description. The information provided in the ticket should be sufficient for any contributor to start working on it. If there is no need to change user documentation, uncheck the Docs Required flag. The Docs Required flag is used to filter out the tickets that require documentation so that our documentation is always up to date.
Info | ||
---|---|---|
| ||
Ignite "master" branch should always be release-ready. Please avoid any commits or merges to the "master" branch unless the whole TeamCity CI suite has passed. |
Changes to a RTC module should be reviewed at least by one maintainer for that module (which may or may not be the same as the main reviewer) before being merged.
Changes to a CTR module (CTR*) may be merged without waiting for review by a maintainer. However it's advisable to ask a maintainer of a CTR module for review and to wait for some time for his/her feedback.
Component | Maintainers | |
---|---|---|
Ignite Core (the rest of internals not covered below) | ||
PME | ||
Rebalance | ||
Affinity | Pavel Kovalenko | |
PDS | ||
Encryption | ||
Compression | ||
MVCC | Igor Seliverstov | |
Transactions | ||
Marshalling (Binary, Optimized, JDK) | ||
Discovery & Communication SPIs | Alexey Goncharuk | |
Ignite Compute API | ||
Ignite Services API | ||
Ignite SQL & Text Queries & JDBC | ||
Ignite Continuous Queries | ||
Machine Learning/Deep Learning (ml, TensorFlow, sub-modules in ml) | Alexey Zinoviev | |
Build System / Releases | Anton Vinogradov | |
TeamCity Bot CTR* | ||
Hadoop Accelerator | ||
Spark Integration | ||
IGFS | ||
.NET API | ||
C++ API | ||
Other thin clients (Python, Node.js, PHP, etc) | ||
ODBC | ||
JDBC | ||
Streamers (JMS, Flume, Kafka, etc.) CTR* | Saikat Maitra | |
Docker, Mesos, YARN integration | ||
AWS, Google Compute Engine, JClouds integration | ||
OSGi integration | ||
Visor | ||
WebSession & WebSession Filter |
PATCH AVAILABLE
state.Info | ||
---|---|---|
| ||
Ask committer to review changes directly.
In case it's hard to determine who's able to review by git history use maintainers list presented above.
for example: "[~avinogradov], Please review my changes."
|
After a pull request goes through rounds of reviews and revisions, it will become ready for merge. A reviewer signals their approval either by a JIRA/Dev. List comment such as “Looks good to me!” (LGTM).
Once a pull request is approved, any committer can merge it.
Special cases:
Exceptions to this rule are rare and made on a case-by-case basis. For example trivial change may be merged by committer without review.
Upsource is an online code review tool. It provides a convenient way to view and discuss changes.
Upsource is optional: it is up to author and reviewer whether to use it or not. Big changes with long discussions are easier to manage in Upsource.
Code author workflow:
Reviewer workflow:
Apache Ignite community agreed to release new version at least once per quarter. However, duration may be longer or shorter. After development of new functionality is finished, QA cycle starts, then release procedure follows.
Master
should become the development branch for the next release.master
. This way master
can be used to develop functionality of the next release. All release fixes get merged to release branch and then to master
.master
branch (or release branch if one exists - in this case changes get merged to release branch and then to master
branch). Changes get merged to master
branch of the project Git via process described at Workflow.master
(or release) branch.Normally, project repo should contain only master
branch, very few branches for ongoing releases and committer's branches ready to be reviewed. Committers and PMC members are in charge to make everyone follow this rule.
Instructions on how to build source and binary releases can be found at DEVNOTES.txt
. Please see "Ignite Release Instructions"
section. On how to make official release please refer to Release Process.
There are several ways how you can make contribution
+------------+ +---------------+ +-----------------+
| | replica | | fork | |
| Apache Git | ==========> | GitHub Mirror | ---------> | John Doe's Fork |
| | | | | |
+------------+ +---------------+ +-----------------+
^ ^ ^
| | |
| +------------------------+ | origin
| upstream | |
| | |
| +-----------------+
| *Apache Git remote handle for committers* | |
+------------------------------------------------| Local clone |
| |
+-----------------+
To start:
You will need to update a local master sometimes (to merge to your development branches sometimes). How to do it:
Add remote for Apache Ignite mirror (you need to do it once)
git remote add upstream https://github.com/apache/ignite.git
Each time when you want to update your local master do the following:
Code Block |
---|
git pull upstream
git checkout master |
To make contribution:
Info | ||
---|---|---|
| ||
Note: Existing pull request should be updated instead of creation of new one. Creation of more than one pull request for one issue forbidden. |
In additional to contributors configuration, committers need to have one more remote reoi - for working with Apache Git repo. It can be added like this:
git remote add apache https://gitbox.apache.org/repos/asf/ignite.git
To push any branch at Apache repo use
git push apache <branch_name>
To apply a pull-request it's strongly recommended using ./scripts/apply-pull-request.sh script. Script takes 'pull-request-id' as a parameter and do next:
git fetch upstream pull/<id>/head:pull-<id>-head
git merge --squash pull-<id>-head
git commit --author=“<saved_author>" -s -m “<comment> - Fixes #<id>.”
Now, you will have one commit at master with all changes from pull-request. Changes can be reviewed again. If you accept all changes and want to push it, do next:
git push apache master
Whenever working on bigger features, committers can also create 'ready to be reviewed' branch ignite-XXXX, where XXXX is the number of the JIRA ticket.
TeamCity should be forced to run all tests on created branch before review. Once tests are passed, the branch has be reviewed by module's maintainer.
Created branch name should be attached to a JIRA ticket and the ticket status should be changed on Patch Available.
Branch can be merged to master on successful review by at least one another committer.
Branch should be deleted on branch merged to master or issue cancelled. Committers are in charge of deleting their branches.
List of points should be checked before push:
Make sure project build log contains no javadoc warnings. Grep build output for "Javadoc Warnings". Covered by Licenses & Javadoc TeamCity task.
In case a new module is added, make sure it contains README.txt at the module's root.
If the contribution is significant (new feature or significant rework of an existed functionality or API) make sure that an example is added to 'ignite-example' and/or an article is written for Apache Ignite Documentation.
Since readme.io does not automatically copy the changes from the current version to the subsequent version, documentation for any new feature that will be released in the next version should be created within the document for the current version. These new pages should be kept hidden until the next version released.
In case new module added, make sure source and binary distributions contains correct license files at modules folders. Covered by Licenses & Javadoc TeamCity task.
Can be checked manually by running command
Code Block |
---|
mvn clean validate -DskipTests=true -P check-licenses |
Make sure each package contains package-info.java with proper description.
Make sure that command
Code Block |
---|
mvn clean package -DskipTests |
finishes without errors.
So, in case, if a patch can't be applied without conflicts on the HEAD of master and the patch has been created by scripts/git-format-patch.sh then a commiter can apply the patch to master by a revision hash, review changes and resolve the conflicts by yourself.