Contribution ways

There are 2 way how you can make contribution

GitHub pull-request
Patch-file

1. GitHub pull-request

 +------------+             +---------------+            +-----------------+

 |            |   replica   |               |    fork    |                 |

 | Apache Git | ==========> | GitHub Mirror | ---------> | John Doe's Fork |

 |            |             |               |            |                 |

 +------------+             +---------------+            +-----------------+

        ^                            ^                            ^

        |                            |                            |

        |                            +------------------------+   | origin

        |                                  upstream           |   |

        |                                                     |   |

        |                                                +-----------------+

        |    *Apache Git remote handle for committers*   |                 |

        +------------------------------------------------|   Local clone   |

                                                         |                 |

                                                         +-----------------+

For contributors

To start:

You need to fork an Apache Ignite mirror on GitHub.
Make a local copy of your Apache Ignite mirror fork. Your remote origin will refer to 'https://github.com/<your_github_uname>/incubator-ignite.git'.
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 next:
```
git checkout master
```
```
git pull upstream
```

To make contribution:

Fix / implement JIRA ticket in your fork. Commit branch to origin (origin = your fork). It's recommended to develop IGNITE-xxx ticket at ignite-xxx branch.
Create pull request from the new remote branch in the fork to master of Apache Ignite mirror. Please, start a title of the pull request from 'IGNITE-xxx'. An email about the pull request will be send to dev-list and the same JIRA comment will be added to the IGNITE-xxx ticket.
TeamCity will automatically trigger builds and label it as a "pull/<pull-request-number>/head". Select this label in the branches dropdown and monitor test results.
Once tests are passed, the pull request can be reviewed and merged by a committer.

For committers

In additional to contributors configuration, commiters need to have one more remote - for working with Apache Git repo. It can be added like this:

git remote add apache https://git-wip-us.apache.org/repos/asf/ignite

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:

Checks that you don't have any uncommitted changes.
Checks you are one master branch and master branch is up-to-date.
Updates local master from Apache git repo.
Fetches pull request to a local branch:

git fetch upstream pull/<id>/head:pull-<id>-head

Saves an author and a comment of the last commit at pull-<id>-head.
Merges from the new branch to master:
- ```
git merge --squash pull-<id>-head
```
Ask you about custom comment or using the saved comment.
Commit to local master. The script automatically sign-off a commit and add "Fixes #<id>." suffix to comment (It will close the pull request, see https://help.github.com/articles/closing-issues-via-commit-messages/):
- ```
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
```

2. Patch-file

2.1 Where to start

You can start by cloning the Ignite GIT repo.

Clone the repo

git clone https://git-wip-us.apache.org/repos/asf/incubator-ignite

2.2 How to generate patches

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:

Committers will not forget to give proper credit to a contributor
Contributor's name and email address show up in the git log

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:

patch can be applied to the HEAD of 'master' branch by "git am <patch-file>" without conflicts.
patch has to have all changes in one commit with comment like "ignite-xxx: Implemented."
patch-file has to have 'patch', 'txt' or 'diff' extension

Patch creation process

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).

Patch validation

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):

patch-file has to have 'patch', 'txt' or 'diff' extension
patch-file has to be attached by JIRA user with contributor role.

Run All for patch (manually)

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.

2.3 For commiters

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

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.

Page tree

How to Contribute