Working with Spark/Openfire source in Eclipse (GitHub)

Version 9

    This guide was created while all the projects were using Ant to build. As Spark has been already moved to Maven and Openfire is in the process, this guide might not apply (i have personally moved to IntelliJ, if one thinks there is a need for IntelliJ guide, i can provide one).

     

    This is a guide of setting up igniterealtime.org projects in Eclipse via GitHub. Replace Project with Spark or Openfire (or other project's name).

     

    IDE AND JDK SETUP AND UPGRADE:

     

    Eclipse setup:

    Launch and select default workspace, select checkbox to remember this selection

    Help > Install New Software > Work with: EGit - http://download.eclipse.org/egit/updates > select both modules and Finish (4.5 - EGit already included?)

    Exit > select checkbox to not ask for confirmation on exit

     

    Eclipse update:

    Help > Check for Updates

     

    Eclipse upgrade:

    Rename old installation to Eclipse-old

    Extract new package to C:\Eclipse

    Launch new eclipse and select old workspace, let it be upgraded

    Delete Eclipse-old

     

    JDK upgrade:

    uninstall old JDK version

    install new JDK version (leave JRE checked)

    uninstall old JRE version

    to run compiled versions add System variable JAVA_HOME with value C:\Program Files (x86)\Java\jdk_version (no trailing slash) (My computer > Advanced > Environment variables)

    on Win7 x64 also edit Path variable and change jdk_version part

    run Eclipse and wait for workspace rebuild

     

    WORKING WITH ORIGINAL REPOSITORY DIRECTLY:

     

    Setup Project in Eclipse with Git support:

    File > Import > Git > Project from Git > Next

    Clone URI > Next https://github.com/igniterealtime/Project.git (Authentication not needed at this point) > Next

    Select only "master" > Next

    Select directory K:\Git\Project > Next

    wait until cloned

    Import as a general project > Next > Finish

    right click imported project and Delete (do not select deleting files on disk)

    File > New > Java Project

    Project name: Project

    Uncheck "use default location" and set directory to K:\Git\Project > Finish

     

    Build project:

    Press Ant icon on the right

    Add buildfiles > select Project > build > build.xml

    right click Ant script > Run As > External Tools Configurations... > select Ant script > JRE tab > select Run in the same JRE as the workspace > Apply > Close

    Press Run Target button to build a project

    run to launch - /target/build/bin/startup.bat (the path and name may vary depending on a project)

     

    Build plugins (example for Spark, there is similar target for Openfire):

    Expand Spark Ant tree

    click on build.plugins > Press Run Target

     

    Update clone from Git:

    right click Project repository in Git Repositories windows > Pull

     

    Test and apply a patch (new branch):

    Team > Switch to > New branch (source "master", set a name without spaces, select Checkout new branch) > Finish

    Team > Apply Patch... > select File > Finish

    Build a project and run for testing

    Remove changes:

    Team > Switch to "master"

    Team > Advanced > Delete Branch (delete new branch)

    Team > Reset (HARD)

     

    Commit changes (when having write access to original Project repository):

    Team > Commit... (set Commit message, drag files with changes from Unstated to Staged window) > Commit and Push (enter login and password, check Save in Secure Store)

    When committed as a branch:

    Go to GitHub and create pull request, wait for Travis CI tests to complete, merge pull request and delete a branch

    Committing without a branch skips Travis CI tests (tests can be skipped when doing pull request also, just merging without waiting for them to complete)

     

    Add a file to Project:

    right click a package/folder > New > File - enter file's name

    Copy or write a source code for this file

    right click this file > Team > Add to Index

    Commit to add this file to repository

     

    Search in the source:

    Click on a project

    Eclipse menu > Search > File... (check Selected resources to only search in selected project)

     

    WORKING WITH FORKS ON GITHUB:

     

    Create a fork of repository (go to original repository on GitHub.com, click on Fork button, select your account)

     

    Setup Project in Eclipse with Git support:

    File > Import > Git > Project from Git > Next

    Clone URI > Next https://github.com/youraccount/Project.git (Authentication not needed at this point) > Next

    Select only "master" > Next

    Select directory K:\Git\Project > Next

    wait until cloned

    Import as a general project > Next > Finish

    right click imported project and Delete (do not select deleting files on disk)

    File > New > Java Project

    Project name: Project

    Uncheck "use default location" and set directory to K:\Git\Project > Finish

     

    Add remotes:

    In Git Repositories window Expand Project repository

    Expand Remotes

    right click Remotes > Create Remote... name: igniterealtime, check Configure Fetch > Change URI: https://github.com/igniterealtime/Project > Save (this should add both push and fetch)

     

    Committing changes to your fork:

    Team > Commit... (set Commit message, drag files with changes from Unstated to Staged window) > Commit and Push (enter login and password, check Save in Secure Store)

     

    Submitting your changes to original repository (Pull request):

    Go to your fork on GitHub.com and press New pull request > Create pull request > add commit message (if needed) > Create pull request

    Wait until original repository maintainers merge your pull request (or decline)

     

    After other changes are committed to original repository, your fork page on GitHub.com shows: "This branch is x commits behind igniterealtime:master."

     

    Updating your fork with Eclipse:

    Expand Project Git repository (Git Repositories window)

    Expand Remotes

    right click Remotes - igniterealtime > Fetch

    Branches > Local > master should already be checked (black icon with checkmark)

    Expand Branches > Remote Tracking

    right click igniterealtime/master > Merge (if no unique changes in local branch, will make fast-forward merge) - Project repository will show: x and arrow pointing upwards

    Expand Remotes

    right click Remotes - origin > Push

     

    Your fork page on GitHub.com will show: "This branch is even with igniterealtime:master."

     

    This can be achieved with GitHub Desktop app:

    Install GitHub Desktop app (login with your GitHub account)

    Press + > Clone > select your Project fork repository > select folder to clone to - K:\Git (will create K:\Git\Project)

    wait until cloned

    right click Project > Open in Git Shell:

    git fetch igniterealtime

    git checkout master (probably already checked)

    git merge igniterealtime/master (if no unique changes in local branch, will make fast-forward merge)

    git push origin master

     

    IMPORTANT (about GitHub's merge and squash feature): GitHub now allows for squashing a few commits in a PR after merging. This creates just one commit in a history, which looks nicer. Usually it doesn't create a problem with fork syncing, if you sync someone's squashed PR commit. But if you work in Eclipse, commit changes to your fork, then do a PR and your PR gets squashed while applying to the master, when you will try to sync your fork as described above, your fork on GitHub will say, that your repository is ahead of a master.

     

    The part about creating a pull request is only important for those who want to submit a patch for one of the projects. It is better to do a pull request on GitHub with your changes (than say attaching your file in the forums). Then a developer with merge permission will review it and merge.

     

    2017.07.24 updated committing part according to Eclipse Neon GUI changes