Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Xtext/Contributor Guide"
Line 1: | Line 1: | ||
{{Xtext}} | {{Xtext}} | ||
− | + | == User Account == | |
− | + | ||
We use eclipse [https://git.eclipse.org/r/ eclipse gerrit review server] to review and manage new contributions. You need to perform the following few steps to be able to use the Gerrit server: | We use eclipse [https://git.eclipse.org/r/ eclipse gerrit review server] to review and manage new contributions. You need to perform the following few steps to be able to use the Gerrit server: | ||
Line 13: | Line 12: | ||
The Xtext team uses [[Eclipse_Oomph_Installer|Oomph]] to setup the developer environment. | The Xtext team uses [[Eclipse_Oomph_Installer|Oomph]] to setup the developer environment. | ||
− | Download The Oomph installer | + | Download The Oomph installer and start it. |
+ | * On the initial page, click on the ''Switch to advanced mode'' button in the top right. | ||
* On the '''Product''' page, select "Eclipse IDE for Eclipse Committers (Mars)" or newer. | * On the '''Product''' page, select "Eclipse IDE for Eclipse Committers (Mars)" or newer. | ||
* On the '''Projects''' page, double-click ''Xtext -> Core'' and select the ''master'' stream. | * On the '''Projects''' page, double-click ''Xtext -> Core'' and select the ''master'' stream. | ||
− | * On the '''Variables''' page, select '' | + | * On the '''Variables''' page, select ''Luna'' as "Target Platform". It is recommended to use the ''SSH (read-write, gerrit)'' setting as "Xtext Git or Gerrit Repository". You may choose yourself which settings to enter for the other options on this wizard page. They are well documented in the Oomph installer (click the question mark in the bottom left). Here is an example how it could finally look like: |
[[File:variables-wiz-page.png]] | [[File:variables-wiz-page.png]] | ||
− | Now you can complete the installation wizard | + | Now you can complete the installation wizard with the ''Finish'' button. |
First Oomph will create a new eclipse installation for you. Downloading required files may take a while. | First Oomph will create a new eclipse installation for you. Downloading required files may take a while. | ||
− | You can close Oomph installer after your fresh eclipse installation starts. | + | You can close the Oomph installer after your fresh eclipse installation starts. |
− | In the started eclipse, you will see a startup tasks execution running. Initially it may take a while because | + | In the started eclipse, you will see a startup tasks execution running. Initially it may take a while because it clones the Xtext git repository. In order to see the setup progress details, click the icon left to "Executing startup tasks" in the status bar. Wait for the setup to complete and restart Eclipse when prompted. |
− | After initial setup is done, you should check which version of JDK is used for | + | After initial setup is done, you should check which version of JDK is used for the JavaSE-1.6 execution environment. Go to ''Eclipse preferences -> Java -> Installed JREs -> Execution Environments''. Select JavaSE-1.6 and set a compatible JRE to Java less than 1.8. |
− | Clean build the workspace. | + | Clean build the workspace after changing this setting. |
[[File:setup-jre-page.png]] | [[File:setup-jre-page.png]] | ||
− | == Contributing | + | == Contributing Changes == |
− | If you followed | + | If you have followed the recommendations in the section above, the Oomph installer has already configured your local repository to push changes to the Xtext Gerrit repository. To contribute your changes, commit them using ''Team -> Commit'' and finally, if you feel ready to push, push them to the remote Gerrit server using ''Team -> Remote -> Push to Gerrit''. |
− | == Contribution | + | === Contribution Monitoring === |
− | After you pushed your first commit to | + | After you have pushed your first commit to Gerrit, it will be reviewed on the [https://hudson.eclipse.org/sandbox/job/xtext.gerrit/ hudson review server]. |
− | If all tests pass a | + | If all tests pass, a manual review will be done by one of the Xtext committers. If everything looks good, your contribution will be pushed to the master repository and you can install it from the regular [https://hudson.eclipse.org/hudson/job/Xtext-nightly-HEAD/ eclipse hudson server]. |
− | == Browse Sources Online | + | === Browse Sources Online === |
− | Xtext and Xtend are hosted in | + | Xtext and Xtend are hosted in git. You can browse the repository in cgit here [http://git.eclipse.org/c/tmf/org.eclipse.xtext.git/ Xtext/Xtend repository]. |
− | + | ||
− | == Helpful | + | === Helpful Sites === |
− | [[Gerrit|Using Gerrit hosted at eclipse]] | + | * [[Gerrit|Using Gerrit hosted at eclipse]] |
---- | ---- | ||
− | == | + | === Using a Git Console Application (optional) === |
− | + | You may use whatever git client you like. The important thing is that finally your local git configuration should look similar to this: | |
<code> | <code> | ||
Line 70: | Line 69: | ||
</code> | </code> | ||
− | You can find the configuration file (called "config") in root of your local repository, in the hidden folder ".git". | + | You can find the configuration file (called "config") in the root of your local repository, in the hidden folder ".git". |
+ | |||
+ | ==== Pulling Changes from the Server ==== | ||
+ | To fetch the last changes run: | ||
− | |||
− | |||
<code>git pull origin master</code> | <code>git pull origin master</code> | ||
− | === Committing | + | ==== Committing Your Changes ==== |
− | After you made your changes to the source code, you have to commit them locally: | + | After you made your changes to the source code, you have to commit them locally: |
+ | |||
+ | <code>git commit -a -s -m "Bug 390852: my first contribution"</code> | ||
+ | |||
+ | -a performs 'add' and 'remove' operations to modified and removed files (new files git does not know about won't be affected)<br> | ||
+ | -s is necessary to 'sign-off' your commit; refer to section [http://wiki.eclipse.org/Xtext/Contributor_Guide#User_Account User Account] to make sure you signed the CLA!<br> | ||
+ | -m stands for message. It's common to refer to an existing bug report, in this example [https://bugs.eclipse.org/bugs/show_bug.cgi?id=390852 390852], in your commit message<br> | ||
+ | Now if you call <code>git status</code>, you will see one outgoing change: | ||
+ | |||
+ | <source lang="bash">MacHuebner:org.eclipse.xtext-test dhuebner$ git status | ||
# Auf Zweig master | # Auf Zweig master | ||
# Ihr Zweig ist vor 'origin/master' um 1 Version. | # Ihr Zweig ist vor 'origin/master' um 1 Version. | ||
Line 86: | Line 95: | ||
</source> | </source> | ||
− | === Pushing to | + | ==== Pushing to Review Server ==== |
− | After you committed the changes to the local git repository, you can push them to | + | After you committed the changes to the local git repository, you can push them to Gerrit by running |
+ | |||
<code>git push origin master</code> | <code>git push origin master</code> | ||
− | === Updating changes with new patches === | + | ==== Updating changes with new patches ==== |
In case a patch has problems and you want to provide an updated patch, you need | In case a patch has problems and you want to provide an updated patch, you need | ||
to | 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 |
Revision as of 09:15, 26 February 2015
User Account
We use eclipse eclipse gerrit review server to review and manage new contributions. 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 authentication and how to generate an SSH key, refer to this site. Make sure that you use the same email 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
The Xtext team uses Oomph to setup the developer environment. Download The Oomph installer and start it.
- On the initial page, click on the Switch to advanced mode button in the top right.
- On the Product page, select "Eclipse IDE for Eclipse Committers (Mars)" or newer.
- On the Projects page, double-click Xtext -> Core and select the master stream.
- On the Variables page, select Luna as "Target Platform". It is recommended to use the SSH (read-write, gerrit) setting as "Xtext Git or Gerrit Repository". You may choose yourself which settings to enter for the other options on this wizard page. They are well documented in the Oomph installer (click the question mark in the bottom left). Here is an example how it could finally look like:
Now you can complete the installation wizard with the Finish button.
First Oomph will create a new eclipse installation for you. Downloading required files may take a while. You can close the Oomph installer after your fresh eclipse installation starts. In the started eclipse, you will see a startup tasks execution running. Initially it may take a while because it clones the Xtext git repository. In order to see the setup progress details, click the icon left to "Executing startup tasks" in the status bar. Wait for the setup to complete and restart Eclipse when prompted.
After initial setup is done, you should check which version of JDK is used for the JavaSE-1.6 execution environment. Go to Eclipse preferences -> Java -> Installed JREs -> Execution Environments. Select JavaSE-1.6 and set a compatible JRE to Java less than 1.8. Clean build the workspace after changing this setting.
Contributing Changes
If you have followed the recommendations in the section above, the Oomph installer has already configured your local repository to push changes to the Xtext Gerrit repository. To contribute your changes, commit them using Team -> Commit and finally, if you feel ready to push, push them to the remote Gerrit server using Team -> Remote -> Push to Gerrit.
Contribution Monitoring
After you have pushed your first commit to Gerrit, it will be reviewed on the hudson review server. If all tests pass, a manual review will be done by one of the Xtext committers. If everything 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.
Helpful Sites
Using a Git Console Application (optional)
You may use whatever git client you like. The important thing is that finally your local 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 the root of your local repository, in the hidden folder ".git".
Pulling Changes from the 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 "Bug 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 is 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 by running
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