Difference between revisions of "Xtext/Contributor Guide"
(→Prerequisites) |
|||
| Line 10: | Line 10: | ||
*Make sure that you use the same mail address for your ssh key as you did for your eclipse account to avoid authentification issues | *Make sure that you use the same mail address for your ssh key as you did for your eclipse account to avoid authentification issues | ||
*You need to sign Eclipse's new [http://wiki.eclipse.org/CLA CLA] to be able to push on Gerrit. You can do that after you log in at the [https://projects.eclipse.org/user/2541 Eclipse projects forge] site, using your eclipse account. | *You need to sign Eclipse's new [http://wiki.eclipse.org/CLA CLA] to be able to push on Gerrit. You can do that after you log in at the [https://projects.eclipse.org/user/2541 Eclipse projects forge] site, using your eclipse account. | ||
| − | |||
| − | |||
| − | |||
| − | |||
== Setup Development Environment == | == Setup Development Environment == | ||
| − | + | Xtext team uses Oomph to setup the developer environment. | |
| − | + | Download oomph installer and start it. | |
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | Follow the installation instruction. | |
| + | When Oomph installer asks you to choose... | ||
| + | - "Product" - select "Eclipse IDE for Eclipse Committers (Mars)" or newer. | ||
| + | - "Project" - select Xtext -> Core. | ||
| + | - "Variables" - select Luna as target platform. Other settings on this wizard page are user dependent and well documented in the Oomph installer. Here is an example how it could finally look like: | ||
| + | [[File:variables-wiz-page.png]] | ||
| − | + | Now you can complete the installation wizard. Click finish. | |
| − | + | First Oomph will create a new eclipse installation for you. Downloading required file may take a while. | |
| − | + | You can close Oomph installer after the new eclipse installation starts. | |
| − | + | In the new eclipse you will see a startup tasks execution running, wait for the setup to complete. Initially it may take a while because of cloning the huge xtext git repository. To see the setup progress details - click the icon left to the "Executing startup tasks" in the status bar. | |
| − | + | After initial setup is done, you should check which version of JDK is used for J2SE-1.5 execution environment by default. Go to Eclipse settings -> Java Installed JREs -> Execution environments. Select J2SE-1.5 and set a compatible JRE to Java less than 1.8. Clean build the workspace. | |
| − | + | [[File:setup-jre-page.png]] | |
| − | + | ||
| − | + | ||
| − | == Using git | + | == Using git as a console application == |
As git client you may use whatever you want. The important thing is, that finally, your git configuration should look similar to this: | As git client you may use whatever you want. The important thing is, that finally, your git configuration should look similar to this: | ||
Revision as of 08:17, 10 December 2014
This page is currently under construction. Community members are encouraged to maintain the page, and make sure the information is accurate.
Contents
Prerequisites
User Account
We use eclipse eclipse gerrit review server to review and manage new contributions. Hence, you need to perform the following few steps to be able to use the Gerrit server:
- Register an Eclipse.org account at dev.eclipse.org. The same account is used for Bugzilla and Gerrit. If you are an Eclipse committer you already have one.
- Define a username
- Upload your public ssh-key for authentication. For more information about ssh authenticatoin and how to generate an ssh key, refer to this site.
- Make sure that you use the same mail address for your ssh key as you did for your eclipse account to avoid authentification issues
- You need to sign Eclipse's new CLA to be able to push on Gerrit. You can do that after you log in at the Eclipse projects forge site, using your eclipse account.
Setup Development Environment
Xtext team uses Oomph to setup the developer environment. Download oomph installer and start it.
Follow the installation instruction.
When Oomph installer asks you to choose...
- "Product" - select "Eclipse IDE for Eclipse Committers (Mars)" or newer.
- "Project" - select Xtext -> Core.
- "Variables" - select Luna as target platform. Other settings on this wizard page are user dependent and well documented in the Oomph installer. Here is an example how it could finally look like:
Now you can complete the installation wizard. Click finish.
First Oomph will create a new eclipse installation for you. Downloading required file may take a while.
You can close Oomph installer after the new eclipse installation starts.
In the new eclipse you will see a startup tasks execution running, wait for the setup to complete. Initially it may take a while because of cloning the huge xtext git repository. To see the setup progress details - click the icon left to the "Executing startup tasks" in the status bar.
After initial setup is done, you should check which version of JDK is used for J2SE-1.5 execution environment by default. Go to Eclipse settings -> Java Installed JREs -> Execution environments. Select J2SE-1.5 and set a compatible JRE to Java less than 1.8. Clean build the workspace.
Using git as a console application
As git client you may use whatever you want. The important thing is, that finally, your git configuration should look similar to this:
[core]
repositoryformatversion = 0
filemode = true
logallrefupdates = true
[remote "origin"]
url = git://git.eclipse.org/gitroot/tmf/org.eclipse.xtext.git
pushurl = ssh://<your account id>@git.eclipse.org:29418/tmf/org.eclipse.xtext.git
fetch = +refs/heads/*:refs/remotes/origin/*
push = HEAD:refs/for/master
[branch "master"]
remote = origin
merge = refs/heads/master
You can find the configuration file (called "config") in root of your local repository, in the hidden folder ".git".
Pulling changes from server
To fetch the last changes run:
git pull origin master
Committing your changes
After you made your changes to the source code, you have to commit them locally:git commit -a -s -m "[390852] my first contribution"-a performs 'add' and 'remove' operations to modified and removed files (new files git does not know about won't be affected)
-s necessary to 'sign-off' your commit; refer to section User Account to make sure you signed the CLA!
-m stands for message. It's common to refer to an existing bug report, in this example 390852 in your commit message
Now if you call
git status, you will see one outgoing change:MacHuebner:org.eclipse.xtext-test dhuebner$ git status # Auf Zweig master # Ihr Zweig ist vor 'origin/master' um 1 Version. # (benutzen Sie "git push" um lokalen Versionen herauszubringen) # nichts einzutragen, Arbeitsverzeichnis sauber
Pushing to review server
After you committed the changes to the local git repository, you can push them to gerrit, just run:
git push origin master
Updating changes with new patches
In case a patch has problems and you want to provide an updated patch, you need to
- go to the gerrit website with your change and copy the Change-Id into your clipboard
- update the commit and paste the Change-Id from your clipboard into the commit message
- push again and the amended commit will be added as an update to the gerrit change
Contribution monitoring
After you pushed your first commit to gerrit, it will be reviewed on the hudson review server. If all tests pass a manuel review will be done by one of the Xtext committers. If all looks good, your contribution will be pushed to the master repository and you can install it from the regular eclipse hudson server.
Browse Sources Online
Xtext and Xtend are hosted in Git. You can browse the repository in cgit here Xtext/Xtend repository.