Xtext/Contributor Guide

Draft Content
This page is currently under construction. Community members are encouraged to maintain the page, and make sure the information is accurate.

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.

Eclipse Distribution

Download "Full eclipse" from Xtext website or use the eclipse DSL Package

Let Buckminster setup your Xcontributor environment

We provide an ant script which installs and runs Buckminster. Buckminster will do the most off necessary steps to crete a contributor workspace for you.

What does buckminster do in detail:

creates an eclipse workspace
clones the Xtext git repository
imports necessary projects in created workspace
creates and sets api baseline
creates and sets a target platform
sets some important workspace settings
performs gerrit setup

Run the script

Run the ant script located here. In unix you can use following commands:

wget -N http://git.eclipse.org/c/tmf/org.eclipse.xtext.git/plain/devtools/org.eclipse.xtext.contributor/workspace.ant
ant -f workspace.ant

If it's the first time you are cloning Xtext repository, the script will ask you to input your bugzilla/gerrit username in order to create the necessary entries in the git configuration file, so you can push to gerrit review server. You can also skip this step by leaving your input empty and manually set up your local git repository. Here you can find a good description.

Start eclipse

Start your eclipse and choose ${user.home}/workspaces/xtext-sources as eclipse workspace

Setup working sets

In "Package Explorer" - view, select "Top level elements -> Working sets"
Select File -> Import -> Team -> Team Project Set.
Point to the following URL http://git.eclipse.org/c/tmf/org.eclipse.xtext.git/plain/devtools/org.eclipse.xtext.contributor/projectSet.psf
Perform import

Using git

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

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.

Helpful sites

Using Gerrit hosted at eclipse

Breadcrumbs