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.
Difference between revisions of "Scout/Contribution/Setup"
(Created page with "= Setup = 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 ...") |
(Update for Scout 8) |
||
| (3 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
= Setup = | = Setup = | ||
| − | In order to | + | In order to push a change to a Scout repository, 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. | + | We try to use a minimal set of tools, i.e. eclipse with [http://www.eclipse.org/egit/ egit] and optionally [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 to contribute without these tools. |
Please also read the [[Scout/Contribution_Guidelines | contribution guidelines]] before you start. | Please also read the [[Scout/Contribution_Guidelines | contribution guidelines]] before you start. | ||
| Line 9: | Line 9: | ||
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. | 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]]) | + | Contribution tracking is made with Bugzilla. You need to know how to 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 == | == Contributor License Agreements == | ||
| Line 23: | Line 23: | ||
== Eclipse Installation == | == Eclipse Installation == | ||
| − | You need an eclipse IDE with [http://www.eclipse.org/egit/ egit] and | + | You need an eclipse IDE with [http://www.eclipse.org/egit/ egit] and optionally [http://www.eclipse.org/mylyn/ mylyn]. If you already have an eclipse installation with these plugins, fine, otherwise you can use the latest [http://www.eclipse.org/downloads/index-developer.php Eclipse for Scout Developers] package that includes both plugins. |
== Java == | == Java == | ||
| − | Scout | + | The required Java version depends on the used Scout version. With Scout 8.0 Java 8 is required, with Scout 7.0 Java 7. Eclipse will tell you if your version is wrong, either by compile errors or by warnings. Make sure to check the problems view. |
| + | |||
| + | === Legacy Tasks === | ||
| + | The following tasks only need to be done if a contribution for an OSGi based Scout version (<=5.0) should be done. You can skip this chapter if you use a newer version. | ||
'''Endorsed Java Mail:''' | '''Endorsed Java Mail:''' | ||
| Line 48: | Line 51: | ||
== SSH Key== | == SSH Key== | ||
| − | An SSH | + | An SSH key is needed for authentication without username/password for pushing changes to the repository. For read-only access it is not necessary. |
| − | + | If you already have an RSA based SSH key you can try to use that one, otherwise you can take the following steps to create a new one using eclipse, or use a tool of your choice (like ssh-keygen, puttygen etc.). | |
* Open Window / Preferences in eclipse | * Open Window / Preferences in eclipse | ||
* Go to General / Network Connections / SSH2 | * Go to General / Network Connections / SSH2 | ||
* Open tab Key Management | * Open tab Key Management | ||
| − | * Generate | + | * Generate RSA Key… . Note that DSA keys are not supported anymore. |
| − | * Comment: | + | * Comment: we typically use our e-mail here |
* Enter Passphrase / Confirm Passphrase | * 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. | * Save in C:\Users\username\.ssh. This is your private key. Make sure to always store it in a save place. | ||
| Line 83: | Line 86: | ||
* spaces instead of tabs | * 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. | + | 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, at least for Java files. |
Your git config file should contain the following entries: | Your git config file should contain the following entries: | ||
| Line 102: | Line 105: | ||
== Getting the Sources == | == Getting the Sources == | ||
| − | + | We recommend to [[Scout/Contributions Cloning Scout Manually|manually clone]] the Scout projects into a new workspace. | |
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
== Gerrit Push Configuration== | == Gerrit Push Configuration== | ||
| + | As a contributor you are not allowed to directly push to the remote GIT repository. Instead, you need to push to Gerrit, but this actually has some great advantages: | ||
| − | + | * A build is triggered automatically after a commit. You will be notified when the build is started and completed. This ensures that no commits that break the build or tests are submitted unnoticed. | |
| − | + | ||
| − | * A build is triggered automatically after a commit. You will be notified when the build is started and completed. | + | |
* A commit can be reviewed and updated, if necessary. | * 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. | 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. | ||
| Line 150: | Line 127: | ||
[[Image:GitContributionStep4.03.gerrit.added.png|400px]] | [[Image:GitContributionStep4.03.gerrit.added.png|400px]] | ||
| + | |||
| + | == Push to Gerrit == | ||
| + | |||
| + | You can now push to Gerrit. Note that compared to other review tools, you don't push a feature branch and create a merge request. Instead, you push your changes to a Gerrit branch which points to the actual branch you want to push to. | ||
| + | |||
| + | Example: If you want to push your changes to releases/8.0.x you need to push to refs/'''for'''/releases/8.0.x. This will be done automatically if you are using the "Push to Gerrit..." menu and your local branch is named accordingly. But you can also use the menu "Push branch..." and enter the mentioned Gerrit branch name manually. | ||
| + | |||
| + | When pushing to Gerrit you need to make sure that your commit comment contains a '''change-id''' and a '''signed-off-by''' entry. This can be done by using the two actions on the top right corner of your EGit commit message text area. | ||
| + | |||
| + | As soon as your push is successful you will receive an email that the build has started. In addition to the verification of Jenkins, a committer needs to review your change. If nothing happens you can always add a reviewer manually so that he will be informed by Gerrit about your change. | ||
| + | |||
| + | For details about Git workflows you can check out [[Scout/Contribution/Git_Workflows]]. | ||
Revision as of 08:33, 2 July 2018
Contents
Setup
In order to push a change to a Scout repository, 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 egit and optionally mylyn and a webbrowser. Many people also use gitextensions or the command line, because more features are available. But it is possible to contribute without these tools.
Please also read the contribution guidelines before you start.
Eclipse.org account
Make sure you have a Eclipse.org account. This will provide access to Eclipse Bugzilla and Eclipse Gerrit.
Contribution tracking is made with Bugzilla. You need to know how to handle Bugzillas for Scout (read Opening new Bugs and Bug Life Cycle)
Contributor License Agreements
In order to contribute to Eclipse Scout, you need to sign the Contributor License Agreements (or CLA).
This is straight forward: connect to projects.eclipse.org and click on Contributor License Agreements. Read the document and answer the questions.
Eclipse Installation
You need an eclipse IDE with egit and optionally mylyn. If you already have an eclipse installation with these plugins, fine, otherwise you can use the latest Eclipse for Scout Developers package that includes both plugins.
Java
The required Java version depends on the used Scout version. With Scout 8.0 Java 8 is required, with Scout 7.0 Java 7. Eclipse will tell you if your version is wrong, either by compile errors or by warnings. Make sure to check the problems view.
Legacy Tasks
The following tasks only need to be done if a contribution for an OSGi based Scout version (<=5.0) should be done. You can skip this chapter if you use a newer version.
Endorsed Java Mail: Due to problems with JAX-WS and JavaMail and JMS (see [1] and [2]) an endorsed directory needs to be provided for the JRE. Download JavaMail and jms from Oracle [3] 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
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 to the repository. For read-only access it is not necessary.
If you already have an RSA based SSH key you can try to use that one, otherwise you can take the following steps to create a new one using eclipse, or use a tool of your choice (like ssh-keygen, puttygen etc.).
- Open Window / Preferences in eclipse
- Go to General / Network Connections / SSH2
- Open tab Key Management
- Generate RSA Key… . Note that DSA keys are not supported anymore.
- Comment: we typically use our e-mail here
- 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.
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.
Git settings
Before cloning update your git settings: Open Window/Preferences Team/Git/Configuration and add entries the necessary entries:
- User Settings: Add user.name and user.email
- File Formatting: Add core.autocrlf=input
- Default pull strategy: Add branch.autosetuprebase=always
- Auto prune on fetch: Add fetch.prune=true
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, at least for Java files.
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
We recommend to manually clone the Scout projects into a new workspace.
Gerrit Push Configuration
As a contributor you are not allowed to directly push to the remote GIT repository. Instead, you need to push to Gerrit, but this actually has some great advantages:
- A build is triggered automatically after a commit. You will be notified when the build is started and completed. This ensures 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....
Click on Finish. Your Push URL should now look similar to
Push to Gerrit
You can now push to Gerrit. Note that compared to other review tools, you don't push a feature branch and create a merge request. Instead, you push your changes to a Gerrit branch which points to the actual branch you want to push to.
Example: If you want to push your changes to releases/8.0.x you need to push to refs/for/releases/8.0.x. This will be done automatically if you are using the "Push to Gerrit..." menu and your local branch is named accordingly. But you can also use the menu "Push branch..." and enter the mentioned Gerrit branch name manually.
When pushing to Gerrit you need to make sure that your commit comment contains a change-id and a signed-off-by entry. This can be done by using the two actions on the top right corner of your EGit commit message text area.
As soon as your push is successful you will receive an email that the build has started. In addition to the verification of Jenkins, a committer needs to review your change. If nothing happens you can always add a reviewer manually so that he will be informed by Gerrit about your change.
For details about Git workflows you can check out Scout/Contribution/Git_Workflows.