Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Lyo/ContributorsGettingStarted"

< Lyo
m
(42 intermediate revisions by 5 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 8: Line 15:
  
 
The Lyo project's Git [http://git.eclipse.org/c/lyo repositories].
 
The Lyo project's Git [http://git.eclipse.org/c/lyo repositories].
 +
 +
'''Please read [[Lyo/GitTips]] if you're new to Git!'''
  
 
== Gerrit and Lyo ==
 
== 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.  
+
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 repository URLs to push to are:
+
  
* OSLC4J core     :  ssh://<userid>@git.eclipse.org:29418/lyo/org.eclipse.lyo.core.git
+
The Lyo Gerrit ssh repository URLs to push to are:
* OSLC Samples  :  ssh://<userid>@git.eclipse.org:29418/lyo/org.eclipse.lyo.server.git
+
 
* OSLC Testsuitessh://<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
+
| OSLC4J core  
 +
| ssh://<userid>@git.eclipse.org:29418/lyo/org.eclipse.lyo.core.git
 +
|-
 +
| OSLC Server
 +
| 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
 +
|-
 +
| OSLC Samples
 +
| ssh://<userid>@git.eclipse.org:29418/lyo/org.eclipse.lyo.docs.git
 +
|-
 +
| LDP (Linked Data Platform)
 +
| ssh://<userid>@git.eclipse.org:29418/lyo/org.eclipse.lyo.ldp.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.
 
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]]
 +
 +
=== SSH configuration tips (Windows, especially) ===
 +
 +
Linux and Mac users can generally use the built-in ssh client and configuration files which are managed by the OS.  You can also use these tips if you want to manage them from EGit, but this information is primarily for Windows users.
 +
 +
Setting up SSH in Eclipse to work with Gerrit:
 +
 +
* Go to the Eclipse Preferences page and expand General -> Network Connections -> SSH2
 +
* Click the Key Management tab
 +
* Click Generate RSA Key - it should look like this:
 +
 +
[[Image:Lyo Eclipse SSH Config.png]]
 +
 +
* Before saving, copy the public key to the clipboard
 +
* Click Save Private Key (you can use the Load Existing Key button later to reload the public key to this dialog)
 +
* Go to https://git.eclipse.org/r/#/settings/ and sign in with your Bugzilla email/passwd and click Profile to see your Gerrit username to use when configuring your connection.  This is different from your Bugzilla username.
 +
* Click on the SSH Public Keys link on the left hand side and click Add Key and paste in your public key from the step above
 +
 +
[[Image:Lyo Gerrit SSH Config.png]]
 +
 +
This should prepare your Eclipse environment to follow the steps above
  
 
== Building and running the code ==
 
== Building and running the code ==
Line 29: Line 86:
 
* [[Lyo/BuildTestSuite| Building and running the OSLC test suite]]
 
* [[Lyo/BuildTestSuite| Building and running the OSLC test suite]]
 
* [[Lyo/BuildBugzilla | Building and running the OSLC Bugzilla sample]]
 
* [[Lyo/BuildBugzilla | Building and running the OSLC Bugzilla sample]]
 
+
* [[Lyo/BuildClient | Building and running the OSLC client]]
  
 
== Lyo contribution process ==
 
== 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:
+
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 [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.
+
* Make sure you have a signed [http://wiki.eclipse.org/Development_Resources/Contributing_via_Git#Eclipse_Foundation_Contributor_License_Agreement Eclipse Contributor License Agreement]. This is a one-time step, but sadly we won't be able to commit your change without a signed CLA even if it solves all integration problems, fights world hunger, and brews coffee.
* 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.
+
* Open a [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Lyo Bugzilla bug] 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.
* 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.
+
* 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" section above.
* Commit your change locally - all commits must include the Bugzilla number in the commit message.  You commit must have the Gerrit Change-Id string in the last paragraph.
+
* (Optional) Create a topic branch for your work.
 +
* 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).
 +
* Commit your change locally - all commits must include the Bugzilla number in the first line of the commit 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.   
 
* Push the code to the appropriate Lyo Gerrit repository.   
 
* Visit the [https://git.eclipse.org/r/ Gerrit review instance] and login  
 
* Visit the [https://git.eclipse.org/r/ Gerrit review instance] and login  
 
* Click on your new review request and add some reviewers
 
* 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 at least one of the project committers as a reviewer. (If you're not sure who, add Samuel Padgett.)
 
** Add any others you think would be able to provide a valuable review
 
** 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 under the eclipse.org web site terms of use."
 
* (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 [http://wiki.eclipse.org/EGit/User_Guide#Amending_Commits the EGit User's Guide] for information on amending commits.
 
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.
Line 51: Line 108:
 
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.
 
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"
  
Older instructions on using GitHub with Lyo can be found [Lyo/LyoGitHub | here ]
+
Here is a [https://wiki.eclipse.org/Lyo/GitTips#Suggested_Workflow suggested workflow].

Revision as of 10:58, 5 August 2014

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.

Please read Lyo/GitTips if you're new to Git!

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 Server 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
OSLC Samples ssh://<userid>@git.eclipse.org:29418/lyo/org.eclipse.lyo.docs.git
LDP (Linked Data Platform) ssh://<userid>@git.eclipse.org:29418/lyo/org.eclipse.lyo.ldp.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

SSH configuration tips (Windows, especially)

Linux and Mac users can generally use the built-in ssh client and configuration files which are managed by the OS. You can also use these tips if you want to manage them from EGit, but this information is primarily for Windows users.

Setting up SSH in Eclipse to work with Gerrit:

  • Go to the Eclipse Preferences page and expand General -> Network Connections -> SSH2
  • Click the Key Management tab
  • Click Generate RSA Key - it should look like this:

Lyo Eclipse SSH Config.png

  • Before saving, copy the public key to the clipboard
  • Click Save Private Key (you can use the Load Existing Key button later to reload the public key to this dialog)
  • Go to https://git.eclipse.org/r/#/settings/ and sign in with your Bugzilla email/passwd and click Profile to see your Gerrit username to use when configuring your connection. This is different from your Bugzilla username.
  • Click on the SSH Public Keys link on the left hand side and click Add Key and paste in your public key from the step above

Lyo Gerrit SSH Config.png

This should prepare your Eclipse environment to follow the steps above

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 you have a signed Eclipse Contributor License Agreement. This is a one-time step, but sadly we won't be able to commit your change without a signed CLA even if it solves all integration problems, fights world hunger, and brews coffee.
  • Open a Bugzilla bug 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" section above.
  • (Optional) Create a topic branch for your work.
  • 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 the commit 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 as a reviewer. (If you're not sure who, add Samuel Padgett.)
    • Add any others you think would be able to provide a valuable 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"

Here is a suggested workflow.

Back to the top