Jump to: navigation, search

Difference between revisions of "Lyo/ContributorsGettingStarted"

< Lyo
(New page: This guide is to help you get started contributing to the Eclipse Lyo project. == Git repositories == Lyo uses Git for source control. Getting both EGit for Eclipse and the git command ...)
 
(Gerrit and Lyo)
(40 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
This guide is to help you get started contributing to the Eclipse Lyo project.
 
This guide is to help you get started contributing to the Eclipse Lyo project.
 +
 +
== Eclipse IP process ==
 +
 +
Before getting started, please take a look at this important information regarding the Eclipse IP process
 +
* [[Development_Resources/IP_Due_Diligence_for_Git_and_Gerrit | IP Due Dilligence for Git and Gerrit]]
 +
* The Eclipse IP [http://www.eclipse.org/legal/EclipseLegalProcessPoster.pdf Flowchart Poster]
 +
* Any contributions are done under the [http://www.eclipse.org/legal/epl-v10.html Eclipse Public License] and [http://www.eclipse.org/org/documents/edl-v10.php Eclipse Distribution License]
  
 
== Git repositories ==
 
== Git repositories ==
Line 9: Line 16:
 
The Lyo project's Git [http://git.eclipse.org/c/lyo repositories].
 
The Lyo project's Git [http://git.eclipse.org/c/lyo repositories].
  
== Setting up a GitHub clone ==  
+
== Gerrit and Lyo ==
 +
 
 +
Lyo uses Gerrit to accept, review and approve code contributions from the community.  '''NOTE:'''  Please see [http://wiki.eclipse.org/Gerrit the Eclipse Gerrit guide ] for information on configuring EGit or the command line to push to the Eclipse Gerrit instance.  You will need to get your unique Gerrit userid by following those instructions.  Using ssh to communicate is recommended and involves registering your public SSH key with Gerrit as described in the instructions.
 +
 
 +
The Lyo Gerrit ssh repository URLs to push to are:
 +
 
 +
{|
 +
| OSLC4J core
 +
| ssh://<userid>@git.eclipse.org:29418/lyo/org.eclipse.lyo.core.git
 +
|-
 +
| OSLC Samples
 +
| ssh://<userid>@git.eclipse.org:29418/lyo/org.eclipse.lyo.server.git
 +
|-
 +
| OSLC Testsuite
 +
| ssh://<userid>@git.eclipse.org:29418/lyo/org.eclipse.lyo.testsuite.git
 +
|-
 +
| OSLC RIOs
 +
| ssh://<userid>@git.eclipse.org:29418/lyo/org.eclipse.lyo.rio.git
 +
|-
 +
| OSLC Client
 +
| ssh://<userid>@git.eclipse.org:29418/lyo/org.eclipse.lyo.client.git
 +
|}
 +
 
 +
Where <userid> is the user ID received when following the instructions in  [http://wiki.eclipse.org/Gerrit the Eclipse Gerrit guide ].  It is not your Bugzilla user ID.
 +
 
 +
Some users, especially when using EGit to configure ssh, have reported needing a file called '''<home>/.ssh/config''' for things to work.  The content of this file should be the following line:
 +
 
 +
IdentityFile .ssh/id_rsa
 +
 
 +
Example of a correctly configured Gerrit Push configuration for the Lyo Core repository:
 +
 
 +
[[Image:Lyo Gerrit Config.png]]
 +
 
 +
== Building and running the code ==
 +
 
 +
For information on how to build and run the various components in Lyo in a development environment, please see the following guides:
 +
 
 +
* [[Lyo/BuildingOSLC4J | Building and running OSLC4J applications]]
 +
* [[Lyo/BuildRIO | Building and running the reference implementations (RIOs)]]
 +
* [[Lyo/BuildTestSuite| Building and running the OSLC test suite]]
 +
* [[Lyo/BuildBugzilla | Building and running the OSLC Bugzilla sample]]
 +
* [[Lyo/BuildClient | Building and running the OSLC client]]
 +
 
 +
== Lyo contribution process ==
  
Rather than cloning the repositories directly from eclipse.org, we recommend you create an account on GitHub and fork the projects repository mirrors there.
+
You're ready to contribute a bug fix or some new functionality to Lyo?  Great. Here's what you need to do:
This will allow you to use GitHub's Pull Request feature to inform project committers when you have a proposed patch or contribution for consideration.
+
  
=== Currently active GitHub mirrors ===
+
* Make sure there is a [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Lyo Bugzilla bug] open for the work that you are doing.  Make a comment in the bug or on the [mailto:lyo-dev.org mailing list] that you want it assigned to you.
* Reference implementations for OSLC ([[Lyo/LyoRio|RIOs]]) :  https://github.com/eclipse/lyo.rio.git
+
* Pull the latest Lyo code from the appropriate [http://git.eclipse.org/c/lyo Lyo git repository] per the instructions in the "Building and running the code" secition above.
* [[Lyo/LyoTestSuite|Test suites]] for OSLC:   https://github.com/eclipse/lyo.testsuite.git
+
* Code your change - make sure you update any copyright headers as needed.  Use existing source if you need to place a new copyright header.   Make sure it references '''both''' the [http://www.eclipse.org/legal/copyrightandlicensenotice.php EPL] and [http://www.eclipse.org/org/documents/edl-v10.php EDL] licenses (see [[Lyo/Licenses]] for more details about this particular choice of dual licensing in Eclipse lyo).
* Example server projects:  https://github.com/eclipse/lyo.server.git
+
* Commit your change locally - all commits must include the Bugzilla number in the first line of thecommit message. Your commit must have the Gerrit Change-Id string in the last paragraph and must include a Signed-off-by.  See [[Lyo/ContributorsGettingStarted#Requirements_for_Lyo_Commits | Requirements for Lyo Commits]]
 +
* Push the code to the appropriate Lyo Gerrit repository. 
 +
* Visit the [https://git.eclipse.org/r/ Gerrit review instance] and login
 +
* Click on your new review request and add some reviewers
 +
** Add at least one of the project committers (fiedler.mf@gmail-dot-com or spadgett@us-dot-ibm-dot-com are good choices) as a reviewer
 +
** Add any others you think would be able to provide a valuable review
 +
* Edit the Bugzilla bug tracking this work and add this statement (only if it is true!!):  "I wrote all this code, and have the rights to contribute it to Eclipse and contribute it under the EPL and EDL"
 +
* (Optional) send a notification to the lyo-dev mailing list that the change is ready for review.
  
=== Setting up Git for use with GitHub ===
+
After the change is reviewed, it may require additional work or amendment based on the review comments.  See [http://wiki.eclipse.org/EGit/User_Guide#Amending_Commits the EGit User's Guide] for information on amending commits.
  
See [http://help.github.com/mac-set-up-git/ MacOS], [http://help.github.com/win-set-up-git/ Windows] or [http://help.github.com/linux-set-up-git/ Linux] instructions for configuring your GitHub SSH keys.
+
Once your change is approved, there is nothing more for you to do - the committers will push the change to the appropriate repository and others can then fetch or pull it.
  
=== Creating a repo on GitHub for use with Lyo ===
+
=== Requirements for Lyo Commits ===
  
This example will use the Lyo RIO project as an example.
+
All Git commits for Lyo must include:
  
* Go to RIO GitHub pagehttps://github.com/eclipse/lyo.rio
+
* '''A descriptive commit message.'''  The first line of the commit message should be the Bug ID and a short summary of the change.  Example: "Bug 12345Add NPE protection to Foo::Bar".   A more detailed explanation of the change on subsequent lines is encouraged.
* Select the Fork button in the upper right to create a new repository on GitHub under your userid
+
* '''A Signed-off-by-line with your name and e-mail.'''  In EGit there is a widget in the upper right of the commit dialog to add this.  Example: "Signed-off-by: Michael Fiedler <fiedler.mf@example.com>".  This asserts you are contributing this commit under the Eclipse IP terms.
[[Image:Lyo-github-fork.png]]
+
* '''A Gerrit Change-ID string. ''' In EGit there is a widget in the upper right of the commit dialog to add this.  Don't worry about the value, EGit will compute it.  Example:  "Change-Id: I0000000000000000000000000000000000000000"
  
This forked repository is the only one you have write access to - the mirror repo you forked it from is read only.
+
== Suggested Git workflow for making a change in Lyo ==
  
=== Clone your GitHub repo on your development system ===
+
The following steps should help minimize the amount of merging you and the committers will have to do to integrate your change
This example uses EGit in Eclipse
+
  
* Go to the Git Repositories view in Eclipse
+
* Before making any changes, make sure you have the latest code from Eclipse
* Click Clone a Git Repository
+
** '''EGit''': In the Git repositories view, right click the repository where you be making a change and select '''Pull'''
* Enter the SSH URL for your GitHub repo - examplessh://git@github.com/mffiedler/lyo.rio.git
+
** '''Command Line'''cd to the git repository and then '''git pull origin master'''
[[Image:Lyo-github-clone.png]]
+
* Create a new local branch to make your change on
* Complete the wizard
+
** '''EGit''':  Expand the repository -> Branches, right click Local -> Switch To -> New Branch.  Name your branch '''BugXXXXX''' where XXXXXX is the Bugzilla number.
* Now, add a remote for the mirror repository (the one you forked from).  This allows you to track and pull incoming changes from other contrbutors
+
** '''Command Line''':  '''git checkout -b BugXXXXXX''' where XXXXXXX is the Bugzilla number
  * Expand the lyo.rio repository, right click Remotes->Create Remote
+
* Code your change
  * Give it the name '''upstream''' and select Configure fetch (you will never push to this remote, only your remote named origin)
+
* Commit your change - add Signed-Off-By and Change-Id as described above.  
  * Enter the URI for the original mirror you forked (as seen above). This example will use the RIO:  https://github.com/eclipse/lyo.rio.git
+
* Merge your change back to the master branch
  * Click Add for a RefSpec.  Pressing space in the Source field should give you the choice '''master [branch]'''. Select it and click Next and Finish.  Your fetch screen should look similar to this:
+
** Checkout the master branch
[[Image:Lyo-github-remote-fetch.png]]
+
*** '''EGit''': Expand repository->Branches->Local, right click master and select '''Checkout'''
  * Click Save (or Save and Fetch)
+
*** '''Command Line''': '''git checkout master'''
  * To retrieve upstream changes from now on, go to the Git Repositories view. Expand your repo -> Remotes->'''upstream''.   Right click the entry with the green arrow and Fetch
+
** (Optional, but good practice) Before merging, repeat the steps above to pull from Eclipse in case anything was committed while you were making your change, especially if your change took a long time to code and test.
[[Image:Lyo-github-fetch-upstream.png]]
+
** Merge your BugXXXXXX branch changes to master
  * Now merge the upstream changes into your local repo.  Right click the repository -> MergeExpand remotes and select upstream/master
+
***'''EGit''': Expand repository->Branches->Local,  right click master and select '''Merge'''. In the merge dialog, select Local->BugXXXXXX
[[Image:Lyo-github-merge-upstream.png]]
+
*** '''Command Line''': git merge BugXXXXXX
  * This fetch and merge process is actually much easier from the command line:
+
* At this point you might have a merge conflict in your workspaceIf so, resolve it manually and do a '''new commit''' for the merge changes.
      * git fetch upstream
+
* Push to Gerrit (see the previous section)
      * git merge upstream/master
+
  
 +
At this point you can delete the branch you made the change on if you are done with it:
  
* At this point, continue on with the [http://wiki.eclipse.org/Lyo/BuildRIO#Build_the_projects directions] to build and run the RIO.
+
* '''EGit''': right click the branch and delete
 +
* '''Command Line''': git branch -D BugXXXXXX
  
== Contributing a change ==
+
Older instructions on using GitHub with Lyo can be found [http://wiki.eclipse.org/Lyo/LyoGitHub here ]
* First, make sure you have a bugzilla open for Product = Lyo at http://bugs.eclipse.org.  You can request in the bug or on the [[mailto:lyo-dev@eclipse.org]] mailing list that it be assigned to you.
+
* Code your change.  Make sure it is your own code.  See
+
* Add the following statement to the bugzilla "I wrote all this code and have the rights to contribute it to Eclipse under the eclipse.org web site terms of use."
+
* Optionally (recommended!!) - attach a patch to the bugzilla as well
+
* Commit your change locally and then push it to your '''origin''' remote.  See instructions above for pushing. '''origin''' is your forked repository on GitHub
+
  * Your commit message '''must''' include the bugzilla ID and a description of the change
+
* Go to the GitHub web interface and click Send Pull Request
+

Revision as of 13:31, 15 November 2012

This guide is to help you get started contributing to the Eclipse Lyo project.

Eclipse IP process

Before getting started, please take a look at this important information regarding the Eclipse IP process

Git repositories

Lyo uses Git for source control. Getting both EGit for Eclipse and the git command line tools are recommended.

The Lyo project's Git repositories.

Gerrit and Lyo

Lyo uses Gerrit to accept, review and approve code contributions from the community. NOTE: Please see the Eclipse Gerrit guide for information on configuring EGit or the command line to push to the Eclipse Gerrit instance. You will need to get your unique Gerrit userid by following those instructions. Using ssh to communicate is recommended and involves registering your public SSH key with Gerrit as described in the instructions.

The Lyo Gerrit ssh repository URLs to push to are:

OSLC4J core ssh://<userid>@git.eclipse.org:29418/lyo/org.eclipse.lyo.core.git
OSLC Samples ssh://<userid>@git.eclipse.org:29418/lyo/org.eclipse.lyo.server.git
OSLC Testsuite ssh://<userid>@git.eclipse.org:29418/lyo/org.eclipse.lyo.testsuite.git
OSLC RIOs ssh://<userid>@git.eclipse.org:29418/lyo/org.eclipse.lyo.rio.git
OSLC Client ssh://<userid>@git.eclipse.org:29418/lyo/org.eclipse.lyo.client.git

Where <userid> is the user ID received when following the instructions in the Eclipse Gerrit guide . It is not your Bugzilla user ID.

Some users, especially when using EGit to configure ssh, have reported needing a file called <home>/.ssh/config for things to work. The content of this file should be the following line:

IdentityFile .ssh/id_rsa

Example of a correctly configured Gerrit Push configuration for the Lyo Core repository:

Lyo Gerrit Config.png

Building and running the code

For information on how to build and run the various components in Lyo in a development environment, please see the following guides:

Lyo contribution process

You're ready to contribute a bug fix or some new functionality to Lyo? Great. Here's what you need to do:

  • Make sure there is a Bugzilla bug open for the work that you are doing. Make a comment in the bug or on the mailing list that you want it assigned to you.
  • Pull the latest Lyo code from the appropriate Lyo git repository per the instructions in the "Building and running the code" secition above.
  • Code your change - make sure you update any copyright headers as needed. Use existing source if you need to place a new copyright header. Make sure it references both the EPL and EDL licenses (see Lyo/Licenses for more details about this particular choice of dual licensing in Eclipse lyo).
  • Commit your change locally - all commits must include the Bugzilla number in the first line of thecommit message. Your commit must have the Gerrit Change-Id string in the last paragraph and must include a Signed-off-by. See Requirements for Lyo Commits
  • Push the code to the appropriate Lyo Gerrit repository.
  • Visit the Gerrit review instance and login
  • Click on your new review request and add some reviewers
    • Add at least one of the project committers (fiedler.mf@gmail-dot-com or spadgett@us-dot-ibm-dot-com are good choices) as a reviewer
    • Add any others you think would be able to provide a valuable review
  • Edit the Bugzilla bug tracking this work and add this statement (only if it is true!!): "I wrote all this code, and have the rights to contribute it to Eclipse and contribute it under the EPL and EDL"
  • (Optional) send a notification to the lyo-dev mailing list that the change is ready for review.

After the change is reviewed, it may require additional work or amendment based on the review comments. See the EGit User's Guide for information on amending commits.

Once your change is approved, there is nothing more for you to do - the committers will push the change to the appropriate repository and others can then fetch or pull it.

Requirements for Lyo Commits

All Git commits for Lyo must include:

  • A descriptive commit message. The first line of the commit message should be the Bug ID and a short summary of the change. Example: "Bug 12345: Add NPE protection to Foo::Bar". A more detailed explanation of the change on subsequent lines is encouraged.
  • A Signed-off-by-line with your name and e-mail. In EGit there is a widget in the upper right of the commit dialog to add this. Example: "Signed-off-by: Michael Fiedler <fiedler.mf@example.com>". This asserts you are contributing this commit under the Eclipse IP terms.
  • A Gerrit Change-ID string. In EGit there is a widget in the upper right of the commit dialog to add this. Don't worry about the value, EGit will compute it. Example: "Change-Id: I0000000000000000000000000000000000000000"

Suggested Git workflow for making a change in Lyo

The following steps should help minimize the amount of merging you and the committers will have to do to integrate your change

  • Before making any changes, make sure you have the latest code from Eclipse
    • EGit: In the Git repositories view, right click the repository where you be making a change and select Pull
    • Command Line: cd to the git repository and then git pull origin master
  • Create a new local branch to make your change on
    • EGit: Expand the repository -> Branches, right click Local -> Switch To -> New Branch. Name your branch BugXXXXX where XXXXXX is the Bugzilla number.
    • Command Line: git checkout -b BugXXXXXX where XXXXXXX is the Bugzilla number
  • Code your change
  • Commit your change - add Signed-Off-By and Change-Id as described above.
  • Merge your change back to the master branch
    • Checkout the master branch
      • EGit: Expand repository->Branches->Local, right click master and select Checkout
      • Command Line: git checkout master
    • (Optional, but good practice) Before merging, repeat the steps above to pull from Eclipse in case anything was committed while you were making your change, especially if your change took a long time to code and test.
    • Merge your BugXXXXXX branch changes to master
      • EGit: Expand repository->Branches->Local, right click master and select Merge. In the merge dialog, select Local->BugXXXXXX
      • Command Line: git merge BugXXXXXX
  • At this point you might have a merge conflict in your workspace. If so, resolve it manually and do a new commit for the merge changes.
  • Push to Gerrit (see the previous section)

At this point you can delete the branch you made the change on if you are done with it:

  • EGit: right click the branch and delete
  • Command Line: git branch -D BugXXXXXX

Older instructions on using GitHub with Lyo can be found here