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 "Xtext/Contributor Guide"
< Xtext
m (→Run the script) |
m (→Let Buckminster setup your Xcontributor environment) |
||
| (19 intermediate revisions by 4 users not shown) | |||
| Line 1: | Line 1: | ||
{{Xtext}} {{:DocumentationGuidelines/DraftHeader}} | {{Xtext}} {{:DocumentationGuidelines/DraftHeader}} | ||
== Prerequisites == | == Prerequisites == | ||
| − | === User Account === | + | === [[User Account]] === |
| − | We use [https://git.eclipse.org/r/ eclipse gerrit review server]. | + | |
| − | * Register an Eclipse.org account at [https://dev.eclipse.org/site_login/createaccount.php dev.eclipse.org]. The same account is used for [https://bugs.eclipse.org/bugs Bugzilla] and [https://git.eclipse.org/r Gerrit]. If you are an Eclipse committer you already have one. | + | We use eclipse [https://git.eclipse.org/r/ 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: |
| − | * [https://git.eclipse.org/r/#settings,http-password Define a username] | + | |
| − | * [https://git.eclipse.org/r/#settings,ssh-keys Upload your public ssh-key] for authentication | + | *Register an Eclipse.org account at [https://dev.eclipse.org/site_login/createaccount.php dev.eclipse.org]. The same account is used for [https://bugs.eclipse.org/bugs Bugzilla] and [https://git.eclipse.org/r Gerrit]. If you are an Eclipse committer you already have one. |
| + | *[https://git.eclipse.org/r/#settings,http-password Define a username] | ||
| + | *[https://git.eclipse.org/r/#settings,ssh-keys Upload your public ssh-key] for authentication. For more information about ssh authenticatoin and how to generate an ssh key, refer to [https://help.github.com/articles/generating-ssh-keys 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 [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. | ||
| + | |||
=== Eclipse Distribution === | === Eclipse Distribution === | ||
| − | Download Full eclipse from [http://www.eclipse.org/Xtext/download.html Xtext website] or use the [http://www.eclipse.org/downloads/ eclipse DSL Package] | + | Download "Full eclipse" from [http://www.eclipse.org/Xtext/download.html Xtext website] or use the [http://www.eclipse.org/downloads/ eclipse DSL Package] |
<br><br> | <br><br> | ||
| − | == | + | == Setup Development 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. | + | We provide an [http://ant.apache.org/manual/install.html ant] script which installs and runs [[Buckminster]]. Buckminster will do the most off necessary steps to crete a contributor workspace for you. |
| − | What | + | What the script does in detail: |
| − | * | + | *creates an eclipse workspace |
| − | * | + | *clones the Xtext git repository |
| − | * | + | *imports necessary projects in created workspace |
| − | * | + | *creates and sets [http://help.eclipse.org/kepler/index.jsp?topic=%2Forg.eclipse.pde.doc.user%2Ftasks%2Fapi_tooling_baseline.htm api baseline] |
| − | * | + | *creates and sets a [http://help.eclipse.org/kepler/index.jsp?topic=%2Forg.eclipse.pde.doc.user%2Fconcepts%2Ftarget.htm target platform] |
| − | * | + | *sets some important workspace settings |
| − | * | + | *performs gerrit setup |
=== Run the script === | === Run the script === | ||
| Line 31: | Line 36: | ||
ant -f workspace.ant | ant -f workspace.ant | ||
</source> | </source> | ||
| + | |||
| + | You might want to tweak the Ant <property ...> at the top of the workspace.ant file to customize the directories where the xtext-sources/ workspace or git clone will be created, and/or where the buckminster and director binaries will be installed. | ||
| + | |||
If it's the first time you are cloning Xtext repository, the script will ask you to input your bugzilla/gerrit [[Xtext/Contributor_Guide#User_Account|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. [[Gerrit|Here]] you can find a good description. | If it's the first time you are cloning Xtext repository, the script will ask you to input your bugzilla/gerrit [[Xtext/Contributor_Guide#User_Account|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. [[Gerrit|Here]] you can find a good description. | ||
| Line 40: | Line 48: | ||
* Point to the following URL http://git.eclipse.org/c/tmf/org.eclipse.xtext.git/plain/devtools/org.eclipse.xtext.contributor/projectSet.psf | * 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 | * Perform import | ||
| − | <br> <br> | + | <br> <br> |
| + | |||
== Using git == | == Using git == | ||
| − | As git client you may use whatever you want | + | As git client you may use whatever you want. The important thing is, that finally, your git configuration should look similar to this: |
| − | + | ||
| − | + | ||
<code> | <code> | ||
| Line 62: | Line 69: | ||
</code> | </code> | ||
| + | You can find the configuration file (called "config") in root of your local repository, in the hidden folder ".git". | ||
=== Pulling changes from server === | === Pulling changes from server === | ||
| − | + | To fetch the last changes run:<br> | |
<code>git pull origin master</code> | <code>git pull origin master</code> | ||
| − | === | + | === Committing your changes === |
| + | After you made your changes to the source code, you have to commit them locally:<br> <code>git commit -a -s -m "[390852] my first contribution"</code><br> -a performs 'add' and 'remove' operations to modified and removed files (new files git does not know about won't be affected)<br> -s 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:<br> <source lang="bash">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 | ||
| + | </source> | ||
| + | |||
| + | === Pushing to review server === | ||
| + | After you committed the changes to the local git repository, you can push them to gerrit, just run:<br> | ||
<code>git push origin master</code> | <code>git push origin master</code> | ||
| − | === | + | === 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 == | == Contribution monitoring == | ||
| Line 82: | Line 103: | ||
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]. | 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]. | ||
<br> | <br> | ||
| + | == Helpful sites == | ||
| + | |||
| + | [[Gerrit|Using Gerrit hosted at eclipse]] | ||
Revision as of 17:33, 13 February 2014
Draft Content
This page is currently under construction. Community members are encouraged to maintain the page, and make sure the information is accurate.
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.
Eclipse Distribution
Download "Full eclipse" from Xtext website or use the eclipse DSL Package
Setup Development 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 the script does 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
You might want to tweak the Ant <property ...> at the top of the workspace.ant file to customize the directories where the xtext-sources/ workspace or git clone will be created, and/or where the buckminster and director binaries will be installed.
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
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.