All changes to Geode codebase are tracked via the ASF JIRA. Anybody contributing to Geode is highly encouraged to create JIRA issue describing the nature of the contribution. Remember that even if you start with sending us a pull request ASF JIRA will be required anyway.
When submitting actual code to Apache Geode in a form of a patch contributors have pretty much two alternatives: GitHub pull request or a git-format patch attached to a JIRA ticket.
This document covers the steps for GitHub pull requests, but if a contributor decides to go JIRA + Attachement route the review step of this document should still apply.
Using GitHub
Fork the Apache Geode mirror project on GitHub - https://github.com/apache/incubator-geode
Clone the apache repository locally so you can start working:
git clone https://git-wip-us.apache.org/repos/asf/incubator-geode.git
After cloning add your fork as an additional remote so you can push code to your fork. Substitute your GitHub username for 'markito' in this example, or use the GitHub 'HTTPS Clone URL':
cd incubator-geode git remote add myfork https://github.com/markito/incubator-geode
Your git remote should look like the following:
git remote -v origin https://git-wip-us.apache.org/repos/asf/incubator-geode.git (fetch) origin https://git-wip-us.apache.org/repos/asf/incubator-geode.git (push) myfork https://github.com/markito/incubator-geode (fetch) myfork https://github.com/markito/incubator-geode (push)
Create a local develop branch (develop is where all new development work goes).
git checkout develop
Geode follows git-flow conventions so if you do have git-flow installed in your system just do:
git flow init
Answer master on the first question ("Which branch should be used for bringing forth production releases?"). Press enter for the remaining questions to select the default options.
Then create your feature branch with the number of the JIRA task that describes your work (fix/feature).
git flow feature start GEODE-41 Switched to a new branch 'feature/GEODE-41' Summary of actions: - A new branch 'feature/GEODE-41' was created, based on 'develop' - You are now on branch 'feature/GEODE-41' Now, start committing on your feature. When done, use: git flow feature finish GEODE-41
If you don't have git flow, you can just create a feature branch manuallygit checkout develop git pull git checkout -b feature/GEODE-41
Complete your work (commits) and in order to update the ticket with your progress
git commit -a
Follow the guidelines for good commit messages. Here's an example:GEODE-526: Fix oplog unit test race condition KRF files are created asynchronously. The test needs to wait for the files to be created before checking header content.
If you've modified source code, execute the precheckin gradle task in order to perform tests related to the components affected by your change. All tests must pass. When in doubt ask on @dev list.
./gradlew precheckin
- When work is complete, consider whether documentation to be updated or created due to the new feature.
If/When needed to push your local work to GitHub use the following command:
git push -u myfork feature/GEODE-41
- Open GitHub web interface and you should see your just pushed branch with a 'Compare & pull request' button
This will lead to Open a pull request page with detailed information on which fork and branch you going from/to. You should add some descriptive information if needed and finally click on Create pull request
- The review process starts and once approved your PR will be merged into develop. if it's not approved or requires some additional work, go back to the commit step.
Accepting the Pull-request
As a reviewer/committer do the review using GitHub or if needed request a ReviewBoard submission.
Once the PR is approved since the GitHub repository is a ready-only mirror you actually need to download the patch and apply. The JIRA ticket must have the link to the patch in the comments section, something like: https://github.com/apache/incubator-geode/pull/6.patch
Alternatively add GitHub as a remote to the ASF clone and just fetch pull requests. For example:
Clone the ASF git repository (if you haven't done yet)
git clone https://git-wip-us.apache.org/repos/asf/incubator-geode.git
Add GitHub remote
git remote add github https://github.com/apache/incubator-geode
(for local review) Fetch the pull request into a feature branch for review
git fetch github pull/6/head:feature/GEODE-41 git checkout feature/GEODE-41 Where: 6 -> PR number feature/GEODE-41 -> local destination branch
(for local review) After review is complete you can merge the feature into develop and remove the branch
git flow feature finish GEODE-41 -F Switched to branch 'develop' Your branch is up-to-date with 'origin/develop'. Updating f7af251..1f2e32a Fast-forward COMPILING.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) Deleted branch feature/GEODE-41 (was 1f2e32a). Summary of actions: - The feature branch 'feature/GEODE-41' was merged into 'develop' - Feature branch 'feature/GEODE-41' has been removed - You are now on branch 'develop'
- Review the changes and rebase if necessary to clean up and modify the history. If there are multiple commits, you may want to squash them together. Remember to add 'close #6' to the last commit message so that github will automatically close the PR.
git log git rebase -i
Finally push the commit the origin repository
git push origin
Given the commit message with the PR number after the push the PR on GitHub will be closed and the JIRA ticket updated.
When using git log command you will see that Author: and Committer: fields are properly updated and credit is given to the contributor. For example:
commit c562d3439577c0bf12cc0e39157761a8dd69da1f Author: Dan Smith <dsmith@pivotal.io> Commit: William Markito <wmarkito@pivotal.io>
Rejecting PRs without committing
If reviewers or committers needs to close a PR if for instance, after proper evaluation it's something that won't get fixed it can be done through an empty commit message
git commit --allow-empty -m "Closes #6 *Won't fix*" git push github develop
Website publishing
Geode website is maintained as part of the repository under the gemfire-site/ folder. We use JBake template management system to turn markdown (.md) templates into static html pages. Those static html pages can then be published as http://geode.incubator.apache.org by committing them to a dedicated publishing branch in Geode's repo: asf-site. The whole process is automated using Gradle tasks and consists of the following steps:
- Make sure that you've got Gradle and Java installed:
https://docs.gradle.org/current/userguide/installation.html
https://gradle.org/downloads/ - Check out our official repo:
$ git clone https://git-wip-us.apache.org/repos/asf/incubator-geode.git
$ cd incubator-geode
$ git checkout develop - Go to the website content folder:
$ cd gemfire-site Edit the content in a usual manner (md files are located under src/jbake/content)
Take a look at you changed by building and running the website via:
$ gradle jbakeRun
and navigating to: http://localhost:8820If you're satisfied with the result make sure to commit the changes to md files to the develop branch
Finally publish the website via running:
$ gradle jbakePublish