Skip to main content
Jump to: navigation, search

Difference between revisions of "Lyo/ContributorsGettingStarted"

< Lyo
m (Contributing a change)
(eclipse ide notice)
 
(53 intermediate revisions by 6 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].
+
 
+
== Setting up a GitHub clone ==
+
 
+
Rather than cloning the repositories directly from eclipse.org, we recommend you create an account on GitHub and fork the projects repository mirrors there.
+
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 ===
+
* Reference implementations for OSLC ([[Lyo/LyoRio|RIOs]]) :  https://github.com/eclipse/lyo.rio.git
+
* [[Lyo/LyoTestSuite|Test suites]] for OSLC:  https://github.com/eclipse/lyo.testsuite.git
+
* Example server projects:  https://github.com/eclipse/lyo.server.git
+
 
+
=== Setting up Git for use with GitHub ===
+
  
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.
+
In order to get your commit merged into master, you need to follow a few steps.
  
=== Creating a repo on GitHub for use with Lyo ===
+
'''Before working on the code'''
  
This example will use the Lyo RIO project as an example.
+
* 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.
  
* Go to RIO GitHub page:  https://github.com/eclipse/lyo.rio
+
'''Developing a change'''
* Select the Fork button in the upper right to create a new repository on GitHub under your userid
+
[[Image:Lyo-github-fork.png]]
+
  
This forked repository is the only one you have write access to - the mirror repo you forked it from is read only.
+
* [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!'''
  
=== Clone your GitHub repo on your development system ===
+
<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)
This example uses EGit in Eclipse
+
</blockquote>
 +
'''Submitting the change for review'''
  
* Go to the Git Repositories view in Eclipse
+
* Submit your commit for the review:
* Click Clone a Git Repository
+
* [http://www.vogella.com/tutorials/Gerrit/article.html#gerritreview_configuration Via Eclipse EGit]
* Enter the SSH URL for your GitHub repo - example:  ssh://git@github.com/mffiedler/lyo.rio.git
+
* 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.
[[Image:Lyo-github-clone.png]]
+
* Complete the wizard
+
* 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
+
  * Expand the lyo.rio repository, right click Remotes->Create Remote
+
  * Give it the name '''upstream''' and select Configure fetch (you will never push to this remote, only your remote named origin)
+
  * 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
+
  * 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:
+
[[Image:Lyo-github-remote-fetch.png]]
+
  * Click Save (or Save and Fetch)
+
  * 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
+
[[Image:Lyo-github-fetch-upstream.png]]
+
  * Now merge the upstream changes into your local repo. Right click the repository -> Merge.  Expand remotes and select upstream/master
+
[[Image:Lyo-github-merge-upstream.png]]
+
  *  This fetch and merge process is actually much easier from the command line:
+
      * git fetch upstream
+
      * git merge upstream/master
+
  
 +
See [https://git.eclipse.org/r/Documentation/intro-user.html Gerrit User Guide] for more information.
  
* At this point, continue on with the [http://wiki.eclipse.org/Lyo/BuildRIO#Build_the_projects directions] to build and run the RIO.
+
== Eclipse IDE notice ==
  
== Contributing a change ==
+
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.
* First, make sure you have a bugzilla open for Product = Lyo at http://bugs.eclipse.org.   You can make a 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
+

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