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 (Git best practices for making a change)
(eclipse ide notice)
 
(28 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 +
= Contributing to Eclipse Lyo =
 +
 
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.
  
== Git repositories ==
+
== Getting started ==
 
+
Lyo uses Git for source control.  Getting both EGit for Eclipse and the git command line tools are recommended.
+
 
+
* [http://eclipse.org/egit/download/ EGit] team provider for git  or [http://git-scm.com/download git command line package].
+
 
+
The Lyo project's Git [http://git.eclipse.org/c/lyo repositories].
+
 
+
== 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 required 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
+
|}
+
 
+
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.
+
 
+
== 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]]
+
  
 +
In order to get your commit merged into master, you need to follow a few steps.
  
== Lyo contribution process ==
+
'''Before working on the code'''
  
You're ready to contribute a bug fix or some new functionality to Lyo? Great. Here's what you need to do:
+
* Register a [https://accounts.eclipse.org/ new Eclipse account]
 +
* Search the [https://bugs.eclipse.org/bugs/query.cgi?format=specific existing bug list]. Look for bugs with ANY status under LYO product and if none matches your problem, [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Lyo file a new bug] on Bugilla '''before working on your contribution'''.
 +
* If you want to discuss your idea before (and after) filing a bug, join the [https://dev.eclipse.org/mailman/listinfo/lyo-dev lyo-dev mailing list].
 +
* Accept and sign the [https://www.eclipse.org/legal/ECA.php ECA]. Instructions on how to sign are on the right side of the page.
  
* 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.
+
'''Developing a change'''
* 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.
+
* 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 commit message.  Your commit must have the Gerrit Change-Id string in the last paragraph.
+
* 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 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.
+
* [https://git.eclipse.org/r/#/admin/projects/?filter=lyo Find the corresponding Gerrit project] and clone it using the command to ''Clone with <code>commit-msg</code> hook''.
 +
* Create a new Git brach from <code>master</code> (best practice is to create a branch <code>b12345-gitignore</code> for a bug ''Bug 12345 .gitignore file missing'').
 +
* Make your changes to the code.
 +
* Make sure you update the license header of the files you modify.
 +
* '''Make a single commit containing all your changes.'''
 +
* Start the first line of your commit message with ''Bug 12345 -'' for a patch that is addressing ''Bug 12345''.
 +
* Make sure to [https://stackoverflow.com/questions/13457203/how-to-add-the-signed-off-by-field-in-the-git-patch include Singed-off-by] line in your commit message (by doing this, you are signing off on a [https://www.eclipse.org/legal/DCO.php Developer Certificate of Origin]). '''Commits without a Singed-off-by line are not accepted!'''
  
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.
+
<blockquote>If you have accidentally made more than one commit, you need to [https://stackoverflow.com/questions/5189560/squash-my-last-x-commits-together-using-git squash the commits]. If you need to update your commit (in case you forgot something or received a feedback you need to address), [https://www.atlassian.com/git/tutorials/rewriting-history#git-commit--amend amend your commit]. [More Git tips are on Lyo wiki] (https://wiki.eclipse.org/Lyo/GitTips)
 +
</blockquote>
 +
'''Submitting the change for review'''
  
== Git suggestions for making a change in Lyo ==
+
* Submit your commit for the review:
 +
* [http://www.vogella.com/tutorials/Gerrit/article.html#gerritreview_configuration Via Eclipse EGit]
 +
* Via the command line: <code>git push origin HEAD:refs/for/master</code>. [https://www.mediawiki.org/wiki/Gerrit/git-review git-review] is recommended for frequent users.
  
The following steps should help minimize the amount of merging you and the committers will have to do to integrate your change
+
See [https://git.eclipse.org/r/Documentation/intro-user.html Gerrit User Guide] for more information.
  
* Before making any changes, make sure you have the latest code from Eclipse
+
== Eclipse IDE notice ==
** '''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'''
+
* Create a new 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
+
* 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 for the paranoid) 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.
+
** Merge your BugXXXXXX 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)
+
  
Older instructions on using GitHub with Lyo can be found [http://wiki.eclipse.org/Lyo/LyoGitHub here ]
+
You can import these projects in Eclipse, they should be loaded via the <code>File &gt; Import &gt; Maven &gt; Existing Maven Projects</code>. This will automatically create the <code>.project</code>, <code>.classpath</code> and <code>.setting</code> files from the <code>pom.xml</code> files. This will ensure the Eclipse project and the Maven POM are in sync. As a side effect, the Eclipse projects will be displayed using their Maven <code>artifactId</code>, not the parent folder name. So <code>org.eclipse.lyo.core</code> will be displayed as <code>oslc4j-core</code>.  In the future, we plan to ensure the eclipse project name and the artifactId are the same and will be avoiding the use of Java package-like names as project names, but these will be breaking changes and will need to be discussed beforehand.

Latest revision as of 09:04, 3 August 2017

Contributing to Eclipse Lyo

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

Getting started

In order to get your commit merged into master, you need to follow a few steps.

Before working on the code

  • Register a new Eclipse account
  • Search the existing bug list. Look for bugs with ANY status under LYO product and if none matches your problem, file a new bug on Bugilla before working on your contribution.
  • If you want to discuss your idea before (and after) filing a bug, join the lyo-dev mailing list.
  • Accept and sign the ECA. Instructions on how to sign are on the right side of the page.

Developing a change

  • Find the corresponding Gerrit project and clone it using the command to Clone with commit-msg hook.
  • Create a new Git brach from master (best practice is to create a branch b12345-gitignore for a bug Bug 12345 .gitignore file missing).
  • Make your changes to the code.
  • Make sure you update the license header of the files you modify.
  • Make a single commit containing all your changes.
  • Start the first line of your commit message with Bug 12345 - for a patch that is addressing Bug 12345.
  • Make sure to include Singed-off-by line in your commit message (by doing this, you are signing off on a Developer Certificate of Origin). Commits without a Singed-off-by line are not accepted!
If you have accidentally made more than one commit, you need to squash the commits. If you need to update your commit (in case you forgot something or received a feedback you need to address), amend your commit. [More Git tips are on Lyo wiki] (https://wiki.eclipse.org/Lyo/GitTips)

Submitting the change for review

  • Submit your commit for the review:
  • Via Eclipse EGit
  • Via the command line: git push origin HEAD:refs/for/master. git-review is recommended for frequent users.

See Gerrit User Guide for more information.

Eclipse IDE notice

You can import these projects in Eclipse, they should be loaded via the File > Import > Maven > Existing Maven Projects. This will automatically create the .project, .classpath and .setting files from the pom.xml files. This will ensure the Eclipse project and the Maven POM are in sync. As a side effect, the Eclipse projects will be displayed using their Maven artifactId, not the parent folder name. So org.eclipse.lyo.core will be displayed as oslc4j-core. In the future, we plan to ensure the eclipse project name and the artifactId are the same and will be avoiding the use of Java package-like names as project names, but these will be breaking changes and will need to be discussed beforehand.

Back to the top