This page provides information about using Git to contribute code changes to JCEF.

Contents

Overview

The JCEF project uses the Git source code management system hosted via GitHub. The easiest way to contribute changes to JCEF is by creating your own personal fork of the JCEF Git repository and submitting pull requests with your proposed modifications. This document is intended as a quick-start guide for developers who already have some familiarity with Git. If you are completely new to Git you might want to review the series of Git tutorials provided by GitHub.

Initial Setup

Git can maintain your changes both locally and on a remote server. To work with Git efficiently the remote server locations must be configured properly.

1. Log into GitHub and create a forked version of the java-cef repository using the Fork button at https://github.com/chromiumembedded/java-cef.

2. Check out JCEF source code as described on the Branches And Building page.

3. Change the remote origin of the JCEF checkout so that it points to your personal forked repository. This is the remote server location that the git push and git pull commands will operate on by default.

cd /path/to/java-cef

# Replace <UserName> with your GitHub user name.
git remote set-url origin https://github.com/<UserName>/java-cef.git

4. Set the remote upstream of the JCEF checkout so that you can merge changes from the main JCEF repository.

git remote add upstream https://github.com/chromiumembedded/java-cef.git

5. Verify that the remotes are configured correctly.

git remote -v

You should see output like the following:

origin    https://github.com/<UserName>/java-cef.git (fetch)
origin    https://github.com/<UserName>/java-cef.git (push)
upstream    https://github.com/chromiumembedded/java-cef.git (fetch)
upstream    https://github.com/chromiumembedded/java-cef.git (push)

6. Configure your name and email address.

git config user.name "User Name"
git config user.email user@example.com

7. Configure the correct handling of line endings in the repository.

# Use this value on Windows. Files will be converted to CRLF line endings
# in the working directory and LF line endings in the object database.
git config core.autocrlf true

# Use this value on other platforms. Files will be unchanged in the working
# directory and converted to LF line endings in the object database.
git config core.autocrlf input

# Cause Git to abort actions on files with mixed line endings if the change is
# not reversible (e.g. changes to binary files that are accidentally classified
# as text).
git config core.safecrlf true

Working With Private Changes

You can now commit changes to your personal repository and merge upstream changes from the main JCEF repository. To facilitate creation of a pull request or the sharing of your code changes with other developers you should make your changes in a branch.

Creating a Branch

Create a new personal branch for your changes.

# Start with the branch that your changes will be based upon.
git checkout master

# Create a new personal branch for your changes.
# Replace <BranchName> with your new branch name.
git checkout -b <BranchName>

Creating a Commit

After making local modifications you can commit them to your personal branch.

# For example, add a specified file by path.
git add path/to/file.txt

# For example, add all existing files that have been modified or deleted.
git add -u

# Commit the modifications locally.
git commit -m "A good description of the fix (issue #1234)"

# Push the modifications to your personal remote repository.
git push origin <BranchName>

Modifying a Commit

You can also modify an existing commit if you need to make additional changes.

# For example, add all existing files that have been modified or deleted.
git add -u

# Update the current HEAD commit with the changes.
git commit --amend

# Push the modifications to your personal remote repository.
# Using the `--force` argument is not recommended if multiple people are sharing the
# same branch.
git push origin <BranchName> --force

Rebasing on Upstream Changes

The main JCEF repository will receive additional commits over time. You will want to include these changes in your personal repository. To keep Git history correct (showing upstream JCEF commits on the JCEF branch instead of on your personal branch) you will need to rebase the local JCEF branch before rebasing your local personal branch.

# Fetch changes from the main JCEF repository. This does not apply them to any
# particular branch.
git fetch upstream

# Check out the local JCEF branch that tracks the upstream JCEF branch.
git checkout master

# Rebase your local JCEF branch on top of the upstream JCEF branch.
# After this command your local JCEF branch should be identical to the upstream JCEF branch.
git rebase upstream/master

# Check out the personal branch that you want to update with changes from the JCEF branch.
# Replace <BranchName> with the name of your branch.
git checkout <BranchName>

# Rebase your personal branch on top of the local JCEF branch.
# After this command your local commits will come after all JCEF commits on the same branch.
git rebase master

# Push the modifications to your personal remote repository.
git push origin <BranchName>

You may get merge conflicts if your personal changes conflict with changes made to the main JCEF repository. For instructions on resolving merge conflicts see this article.

For more information on using the rebase command go here.

Deleting a Branch

Once you no longer need a branch you can delete it both locally and remotely. Do not delete branches that are associated with open pull requests.

# Delete the branch locally.
git branch -D <BranchName>

# Delete the branch remotely.
git push origin --delete <BranchName>

Cleaning a Checkout

You can remove all local changes from your checkout using the below commands.

# Check the current state of the repository before deleting anything.
git status

# Remove all non-committed files and directories from the local checkout.
git clean -dffx

# Remove all local commits from the current branch and reset branch state to match
# origin/master. Replace "origin/master" with a different remote branch name as appropriate.
git reset --hard origin/master

Working With Pull Requests

Once your personal changes are complete you can request that they be merged into the main JCEF repository. This is done using a pull request. Before submitting a pull request you should:

Rebase your changes on the upstream JCEF branch (see “Rebasing on Upstream Changes”).
Fix any coding style issues (see “Coding Style”).
Find or create an appropriate issue in the JCEF issue tracker. Make sure the issue number is referenced in your commit description.
Include new or modified unit tests as appropriate to the functionality.
Remove unnecessary or unrelated changes.

Coding Style

JCEF uses the Chromium coding style. Changes to files should match the existing style in that file.

Creating a Pull Request

Pull requests can only be created from a public repository that was forked using the GitHub interface. Push your branch to your fork and then create the pull request as described here. Pull requests will only be accepted if they meet the requirements described above.

# Push your branch to your fork for PR submission.
git push origin <BranchName>

Reviewing a Pull Request

Your pull request will be reviewed by one or more JCEF developers. Please address any comments and update your pull request. The easiest way to update a pull request is by pushing new commits to the same branch – those new commits will be automatically reflected in the pull request. Once your changes are deemed acceptable they will be squashed and merged into the main JCEF repository.

The contents of a pull request can also be downloaded as a patch file and applied to your local Git checkout:

# Download the patch file (replace {pull_no} with the PR number).
curl -L https://github.com/chromiumembedded/java-cef/pull/{pull_no}.diff -o name.patch

# Apply the patch file to your local Git checkout.
git apply name.patch