|
|
| (3 intermediate revisions by 2 users not shown) |
| Line 1: |
Line 1: |
| − | = Setup =
| + | The Scout documentation has been moved to https://eclipsescout.github.io/. |
| − | In order to work efficiently as a scout committer you need to setup your tools correctly. Here, we try to describe a setup that is simple and working. You only need to do this once.
| + | |
| − | | + | |
| − | We try to use a minimal set of tools, i.e. eclipse with [http://www.eclipse.org/egit/ egit] and [http://www.eclipse.org/mylyn/ mylyn] and a webbrowser. Many people also use [https://code.google.com/p/gitextensions/ gitextensions] or the command line, because more features are available. But it is possible contribute without these tools.
| + | |
| − | | + | |
| − | Please also read the [[Scout/Contribution_Guidelines | contribution guidelines]] before you start.
| + | |
| − | | + | |
| − | == Eclipse.org account ==
| + | |
| − | Make sure you have a [https://dev.eclipse.org/site_login/createaccount.php Eclipse.org account]. This will provide access to Eclipse Bugzilla and Eclipse Gerrit.
| + | |
| − | | + | |
| − | Contribution tracking is made with Bugzilla. You need to know how handle Bugzillas for Scout (read [[Scout/Contribution#Opening_new_Bugs|Opening new Bugs]] and [[Scout/Contribution#Bug_Life_Cycle|Bug Life Cycle]])
| + | |
| − | | + | |
| − | == Contributor License Agreements ==
| + | |
| − | In order to contribute to Eclipse Scout, you need to sign the [[CLA|Contributor License Agreements (or CLA)]].
| + | |
| − | | + | |
| − | This is straight forward: connect to [https://projects.eclipse.org/user/login/sso projects.eclipse.org] and click on Contributor License Agreements. Read the document and answer the questions.
| + | |
| − | | + | |
| − | [[Image:CLA_01_home.png|400px]]
| + | |
| − | | + | |
| − | [[Image:CLA_02_questions.PNG|300px]]
| + | |
| − | | + | |
| − | [[Image:CLA 03 form.png|300px]]
| + | |
| − | | + | |
| − | == Eclipse Installation ==
| + | |
| − | You need an eclipse IDE with [http://www.eclipse.org/egit/ egit] and preferrably [http://www.eclipse.org/mylyn/ mylyn]. For development for the luna release you can use the latest [http://www.eclipse.org/downloads/index-developer.php Eclipse for Scout Developers] package that includes both plugins.
| + | |
| − | | + | |
| − | == Java ==
| + | |
| − | Scout Bundles are still compatible to Java 1.6. Therefore you should configure at least JRE 1.6 in eclipse and preferably also JRE 1.7.
| + | |
| − | | + | |
| − | '''Endorsed Java Mail:'''
| + | |
| − | Due to problems with JAX-WS and JavaMail and JMS (see [http://www.eclipse.org/forums/index.php?t=msg&th=202571&start=0&S=208ef84eb179d95846ecb91b4bb1da68] and [http://wiki.eclipse.org/Scout/Tutorial/3.8/IMAP_Step-by-Step#Make_your_project_JavaMail_aware]) an endorsed directory needs to be provided for the JRE. Download JavaMail and jms from Oracle [http://www.oracle.com/technetwork/java/index-138643.html] and put it into the endorsed directory of the JRE. Your directory structure should look like that:
| + | |
| − | | + | |
| − | jre\lib\endorsed\javax.mail.jre16_1.4.3.jar
| + | |
| − | jre\lib\endorsed\javax.jms_1.1.0.jar
| + | |
| − | | + | |
| − | The two jar files should appear in the list of system libraries in the Eclipse JRE Definition (open Preferences->Java->Installed JREs, Edit...). If not either restart eclipse or add them manually.
| + | |
| − | | + | |
| − | '''tools.jar:''' For compiling the JAX-WS plugins you need to add the tools.jar:
| + | |
| − | | + | |
| − | In Eclipse open Preferences->Java->Installed JREs->Add->Standard VM and select your JRE.
| + | |
| − | * Click on "Edit..."
| + | |
| − | * Click on "Add External JARs..."
| + | |
| − | * Select <jdk>\lib\tools.jar
| + | |
| − | | + | |
| − | [[Image:Scout_Add_JRE.png|400px]]
| + | |
| − | | + | |
| − | In Java->Installed JREs->Execution Environments select the correct JRE for JavaSE-1.6 and JavaSE-1.7.
| + | |
| − | | + | |
| − | == SSH Key==
| + | |
| − | An SSH Key is needed for authentication without username/password for pushing changes into the repository. For read-only access it is not necessary.
| + | |
| − | | + | |
| − | Here is how you create a new SSH Key in eclipse.
| + | |
| − | | + | |
| − | * Open Window / Preferences in eclipse
| + | |
| − | * Go to General / Network Connections / SSH2
| + | |
| − | * Open tab Key Management
| + | |
| − | * Generate DSA Key…
| + | |
| − | * Comment: email
| + | |
| − | * Enter Passphrase / Confirm Passphrase
| + | |
| − | * Save in C:\Users\username\.ssh. This is your private key. Make sure to always store it in a save place.
| + | |
| − | | + | |
| − | [[Image:GitContribution_createSSHKey.png|450px]]
| + | |
| − | | + | |
| − | In order to be able to push to git and gerrit, you need to upload your SSH key.
| + | |
| − | | + | |
| − | Gerrit is located here: https://git.eclipse.org/r/. Sign in with your email and password and add the key.
| + | |
| − | | + | |
| − | [[Image:GitContributionGerritSSHKey.png|300px]]
| + | |
| − | | + | |
| − | == Git settings ==
| + | |
| − | Before cloning update your git settings: Open Window/Preferences Team/Git/Configuration and add entries the necessary entries:
| + | |
| − | | + | |
| − | [[Image:gitSettings.png | 400px]]
| + | |
| − | | + | |
| − | * '''User Settings:''' Add <tt>user.name</tt> and <tt>user.email</tt>
| + | |
| − | * '''File Formatting:''' Add <tt>core.autocrlf=input</tt>
| + | |
| − | * '''Default pull strategy:''' Add <tt>branch.autosetuprebase=always</tt>
| + | |
| − | * '''Auto prune on fetch:''' Add <tt>fetch.prune=true</tt>
| + | |
| − | | + | |
| − | Contributed text files are stored in the repository in the following way:
| + | |
| − | * LF line endings
| + | |
| − | * UTF-8 formatted
| + | |
| − | * spaces instead of tabs
| + | |
| − | | + | |
| − | Formatting is done in eclipse with the .settings files linked to every project. Therefore, if everything is configured right, you do not need to worry about formatting.
| + | |
| − | | + | |
| − | Your git config file should contain the following entries:
| + | |
| − | | + | |
| − | [user]
| + | |
| − | name = Full User Name
| + | |
| − | email = ...@bsiag.com
| + | |
| − | [core]
| + | |
| − | autocrlf = input
| + | |
| − | [fetch]
| + | |
| − | prune = true
| + | |
| − | [branch]
| + | |
| − | autosetuprebase = always
| + | |
| − | | + | |
| − | Make sure that the email is registered in Gerrit https://git.eclipse.org/r/#/settings/.
| + | |
| − | | + | |
| − | If you are using multiple gerrit instances, make sure the email you use in the git settings is also registered in all gerrit instances (here the email is case sensitive). It is possible to register multiple emails in gerrit: Open https://git.eclipse.org/r/#/settings/contact to register a new email address. You will get an verification email containing a link. Clicking on the link does not always work, so just copy and paste it to the browser.
| + | |
| − | | + | |
| − | == Getting the Sources ==
| + | |
| − | There are [http://wiki.eclipse.org/EGit/User_Guide/Project_Set_File team project set] files available for easier initial cloning. Import the project set with File->Import->Team->Team Project Set.
| + | |
| − | Usually the Scout RT and Scout SDK are developed in different workspaces.
| + | |
| − | | + | |
| − | http://git.eclipse.org/c/scout/org.eclipse.scout.rt.git/plain/org.eclipse.scout.rt.team-project-set/scoutRT.psf?h=develop
| + | |
| − | | + | |
| − | http://git.eclipse.org/c/scout/org.eclipse.scout.sdk.git/plain/org.eclipse.scout.sdk.team-project-set/scoutSDK.psf?h=develop
| + | |
| − | | + | |
| − | Alternatively you can also [http://wiki.eclipse.org/Scout/Contributions_Cloning_Scout_Manually#GIT_Repositories clone the sources manually] (''only experienced scout contributors should do this - beginners should use the team project sets'').
| + | |
| − | | + | |
| − | == Compiling in Eclipse ==
| + | |
| − | | + | |
| − | === Scout RT ===
| + | |
| − | In order to compile everything you need to set the Target Platform. There are multiple target files available, because Scout needs to be compatible with multiple eclipse versions. In most cases you can use eclipse-3.6.target. Open the file
| + | |
| − | | + | |
| − | /org.eclipse.scout.target/eclipse-3.6.target
| + | |
| − | | + | |
| − | and select ''Set as Target Platform''.
| + | |
| − | | + | |
| − | === Scout SDK ===
| + | |
| − | The SDK Plugins don't need a specific target. Instead Scout must be installed in the Eclipse IDE so that the SDK can use the commons plugin from Scout.
| + | |
| − | | + | |
| − | Furthermore there are compatibility fragments to abstract various Eclipse Platform API differences between the supported versions. Just close the ones that do not match the Eclipse version you are testing with (e.g. when developing with Eclipse Kepler, close all except 'org.eclipse.scout.sdk.compatibility.v43.fragment').
| + | |
| − | | + | |
| − | === Using the sources with your Project ===
| + | |
| − | You can import the source projects in a workspace with your scout project. If a plugin is in the workspace and in the target, the one in the workspace is used (sometimes there are refresh problems).
| + | |
| − | | + | |
| − | Note: When a Scout project is created with the SDK, only the installed project is considered and not the target platform.
| + | |
| − | | + | |
| − | == Gerrit Push Configuration==
| + | |
| − | | + | |
| − | Although it is possible to push direclty to git, the common process is to push to Gerrit. We do this because
| + | |
| − | | + | |
| − | * A build is triggered automatically after a commit. You will be notified when the build is started and completed. That way we make sure that no commits that break the build or tests are submitted unnoticed.
| + | |
| − | * A commit can be reviewed and updated, if necessary.
| + | |
| − | | + | |
| − | In the previous step we imported the Scout repository read-only. To be able to push our feature branches and patches, we have to configure the Push URL to use Gerrit where write access is granted.
| + | |
| − | Therefore we change the push URL to point to Gerrit:
| + | |
| − | | + | |
| − | ssh://[username]@git.eclipse.org:29418/scout/[repository_name].git
| + | |
| − | | + | |
| − | [username] is your committer Id. Expand the ''Remotes'' directory, right-click on ''origin'' and select ''Gerrit Configuration...''.
| + | |
| − | | + | |
| − | [[Image:GitContributionStep4.01.configure.push.url.png|400px]]
| + | |
| − | [[Image:GitContributionStep4.02.add.gerrit.png|400px]]
| + | |
| − |
| + | |
| − | Click on ''Finish''. Your Push URL should now look similar to
| + | |
| − | | + | |
| − | [[Image:GitContributionStep4.03.gerrit.added.png|400px]]
| + | |
| − | | + | |
| − | | + | |
| − | Next: see [[Scout/Contribution/Git_Workflows]]
| + | |
