Skip to main content

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.

Jump to: navigation, search

Difference between revisions of "Henshin/Committer Instructions"

(Set-up)
(Set-up)
 
(12 intermediate revisions by 2 users not shown)
Line 1: Line 1:
Henshin uses [https://git.eclipse.org/r/#/ Gerrit] for handling code reviewing and merging. This implies specific processes when setting up the development environment and pushing changes. See also the official primer for [https://www.eclipse.org/community/eclipse_newsletter/2014/july/article3.php Contributing to Eclipse Projects via Gerrit].
+
This page provides two important types of '''Instructions to Henshin committers''': The set-up for working on the codebase with Gerrit, and the instructions for importing projects and resolving their dependencies in your local workspace.
  
 
== Set-up ==
 
== Set-up ==
 +
 +
Henshin uses [https://git.eclipse.org/r/#/ Gerrit] for handling code reviewing and merging. This implies specific processes when setting up the development environment and pushing changes. See also the official primer for [https://www.eclipse.org/community/eclipse_newsletter/2014/july/article3.php Contributing to Eclipse Projects via Gerrit].
 +
 
The following steps are for setting up the development environment based on eGit, Eclipse's git integration. Steps may vary if you don't want to use eGit.
 
The following steps are for setting up the development environment based on eGit, Eclipse's git integration. Steps may vary if you don't want to use eGit.
  
Line 12: Line 15:
 
#* In the same manner, you can view and change your committer name using the ''user.name'' environment variable.
 
#* In the same manner, you can view and change your committer name using the ''user.name'' environment variable.
 
# To ensure correct handling of line endings when using Windows, please use the following git configs: ''core.autocrlf=true'' and ''core.filemode=false''. If you have dirty projects due to Windows line endings, try a hard reset after setting the config.
 
# To ensure correct handling of line endings when using Windows, please use the following git configs: ''core.autocrlf=true'' and ''core.filemode=false''. If you have dirty projects due to Windows line endings, try a hard reset after setting the config.
# In Eclipse, clone the Henshin repository using one of the given URLs (git, http, ssh) given at the [https://git.eclipse.org/c/henshin/org.eclipse.emft.henshin.git repository website]. We recommend the following workflow:
+
# In Eclipse, clone the Henshin repository using one of the URLs (git, http, ssh) given at the [https://git.eclipse.org/c/henshin/org.eclipse.emft.henshin.git repository website]. We recommend the following workflow. If relevant, see below for a frequent error related to push rights.
 
#* For cloning the initial state of the repo, use the (read-only) [git://git.eclipse.org/gitroot/henshin/org.eclipse.emft.henshin.git GIT repository URL]. Cloning the entire Repo via the SSH URL may lead to timeouts.
 
#* For cloning the initial state of the repo, use the (read-only) [git://git.eclipse.org/gitroot/henshin/org.eclipse.emft.henshin.git GIT repository URL]. Cloning the entire Repo via the SSH URL may lead to timeouts.
#* After cloning, change the repository location to the [ssh://user_id@git.eclipse.org:29418/henshin/org.eclipse.emft.henshin SSH repository URL] (do ''git remote set-url origin <gerrit-url>'', or follow the [https://www.eclipse.org/community/eclipse_newsletter/2014/july/article3.php eGit instructions])
+
#* After cloning, change the repository location to the [ssh://user_id@git.eclipse.org:29418/henshin/org.eclipse.emft.henshin SSH repository URL] (do ''git remote set-url origin <gerrit-url>'', or follow the [https://www.eclipse.org/community/eclipse_newsletter/2014/july/article3.php eGit instructions]). Don't forget to substitute ''user_id'' in the URL by your actual Gerrit username, which can be found [https://git.eclipse.org/r/#/settings/ here].
 
# In the Git perspective, open the Repository: ''Remotes -> '' Right click on ''origin -> Gerrit Configuration... -> Finish''.
 
# In the Git perspective, open the Repository: ''Remotes -> '' Right click on ''origin -> Gerrit Configuration... -> Finish''.
 
# Follow the steps outlined in the next section.
 
# Follow the steps outlined in the next section.
 +
 +
After pushing a change, a corresponding entry on [https://git.eclipse.org/r/#/ Gerrit] has been created. Please invite (a subset of) the other committers as reviewers, doing this for all changes.
 +
 +
=== Frequent problem: no push rights ===
 +
 +
A frequent error message is:
 +
 +
Repository https://username@git.eclipse.org/r/henshin/org.eclipse.emft.henshin
 +
prohibited by Gerrit: not permitted: update
 +
error: branch refs/heads/master:
 +
To push into this reference you need 'Push' rights.
 +
User: username
 +
Contact an administrator to fix the permissions."
 +
 +
This error message occurs if you're pushing to one of the read-only repository URLs. Please follow the instructions above, especially the part about changing the repository location.
 +
 +
[[category:Henshin]][[Category:Modeling]]
  
 
==<span id="imports"></span>Importing projects into your workspace and resolving dependencies ==
 
==<span id="imports"></span>Importing projects into your workspace and resolving dependencies ==
Line 26: Line 46:
 
* Plug-ins ''org.eclipse.emf.henshin.{edit,editor}'': The tree-based editor
 
* Plug-ins ''org.eclipse.emf.henshin.{edit,editor}'': The tree-based editor
 
<br />
 
<br />
All plug-in projects are contained in the ''plugins'' folder in the root directory of our Git repo. Import the plug-ins you want to work on '''as Eclipse projects''' into your workspace. Depending on your selection, you may encounter various build errors. Resolve the missing dependencies as follows:
+
All plug-in projects are contained in the ''plugins'' folder in the root directory of our Git repo. Import the plug-ins you want to work on '''as Eclipse projects''' into your workspace. Depending on your selection, you may encounter various build errors. To resolve them, install dependencies as necessary. The provided links refer to ''update sites'' and '''cannot''' be opened in the browser. Use them to install the dependencies in Eclipse via ''Help'' -> ''Install New Software''.
  
* On build errors for ''org.eclipse.emf.henshin.diagram'', use the Eclipse Marketplace (in ''Help'' menu) to install the ''Graphical Modeling Framework Tooling'' feature.
+
* [http://download.eclipse.org/releases/oxygen/ Papyrus for UML]: needed for ''org.eclipse.emf.henshin.diagram''. In the update site, find Papyrus in the ''Modeling'' category, or by using the filter. Papyrus provides some legacy components of GMF Tooling that are required by Henshin's GMF-based diagram editor.
* On build errors for ''org.eclipse.emf.henshin.giraph'', use the Eclipse Marketplace  to install the ''Maven Integration for Eclipse'' feature.
+
* [http://download.eclipse.org/technology/m2e/releases Maven Integration for Eclipse]: needed for ''org.eclipse.emf.henshin.giraph''.
* On  build errors for the ''org.eclipse.emf.henshin.text'' projects, use the Eclipse Marketplace to install the ''Eclipse Xtext'' feature. On further build errors, trigger the Xtext generation process: navigate to ''org.eclipse.emf.henshin.text -> GenerateHenshin_text.mwe2'', right click and do ''Run As -> MWE2 Workflow''.
+
* [http://download.eclipse.org/modeling/tmf/xtext/updates/composite/releases/ Eclipse Xtext]: needed for ''org.eclipse.emf.henshin.text'' projects. On further build errors, trigger the Xtext generation process: navigate to ''org.eclipse.emf.henshin.text -> GenerateHenshin_text.mwe2'', right click and do ''Run As -> MWE2 Workflow''.
* On build errors for ''org.eclipse.emf.henshin.text.transformation'', use the Eclipse Marketplace to install the ''QVT Operational'' feature. Navigate to the ''Metamodel Mappings'': right click the package ''org.eclipse.emf.henshin.text.transformation'' -> ''Properties'' -> ''Metamodel Mappings''. There add mappings for ''org.eclipse.emf.henshin.model/model/henshin.ecore'' and ''org.eclipse.emf.henshin.text/model/generated/Henshin_text.ecore'': ''Add'' -> ''Browse'' -> navigate to .ecore-file.
+
* [http://download.eclipse.org/mmt/qvto/updates/releases QVT Operational]: needed for ''org.eclipse.emf.henshin.text.transformation''. Navigate to the ''Metamodel Mappings'': right click the project ''org.eclipse.emf.henshin.text.transformation'' -> ''Properties'' -> ''Metamodel Mappings''. There add mappings for ''org.eclipse.emf.henshin.model/model/henshin.ecore'' and ''org.eclipse.emf.henshin.text/model/generated/Henshin_text.ecore'': ''Add'' -> ''Browse'' -> navigate to .ecore-file.
* On build errors for ''org.eclipse.emf.henshin.interpreter.ui'', ''org.eclipse.emf.henshin.multicda.cpa'' or ''org.eclipse.emf.henshin.text.transformation.tests'', use the Eclipse Marketplace to install the ''EMF Compare'' feature.
+
* [http://download.eclipse.org/modeling/emf/compare/updates/releases EMF Compare]: needed for ''org.eclipse.emf.henshin.interpreter.ui'', ''org.eclipse.emf.henshin.multicda.cpa'' and ''org.eclipse.emf.henshin.text.transformation.tests''.
* On build errors for ''org.eclipse.emf.henshin.multicda.cpa'', install the AGG Runtime from the Eclipse Orbit Update Site (Help -> Install new software -> Work with [http://download.eclipse.org/tools/orbit/downloads/drops/R20160520211859/repository/ this URL] and use the filter to find the AGG Runtime)
+
* [http://download.eclipse.org/tools/orbit/downloads/drops/R20160520211859/repository/ AGG Runtime]: needed for ''org.eclipse.emf.henshin.multicda.cpa''. During installation filter for ''AGG Runtime'' to find the package.
  
== Pushing changes ==
 
  
After pushing a change, a corresponding entry on [https://git.eclipse.org/r/#/ Gerrit] has been created. Please invite (a subset of) the other committers as reviewers, doing this for all changes.
+
To resolve further build errors in ''org.eclipse.emf.henshin.adapters.xtext'' right click the project -> ''Properties'' -> ''Resource'' and set the text file encoding to ''Other: UTF-8''.
 
+
[[category:Henshin]][[Category:Modeling]]
+

Latest revision as of 12:59, 25 August 2020

This page provides two important types of Instructions to Henshin committers: The set-up for working on the codebase with Gerrit, and the instructions for importing projects and resolving their dependencies in your local workspace.

Set-up

Henshin uses Gerrit for handling code reviewing and merging. This implies specific processes when setting up the development environment and pushing changes. See also the official primer for Contributing to Eclipse Projects via Gerrit.

The following steps are for setting up the development environment based on eGit, Eclipse's git integration. Steps may vary if you don't want to use eGit.

  1. To be able to push commits to Gerrit, please register an Eclipse account and log into Gerrit.
  2. If you don't have one yet, generate a SSH RSA key pair: do ssh-keygen -t rsa in the git shell.
  3. Register your public key at https://git.eclipse.org/r/#/settings/ssh-keys
  4. Make sure your local git's committer e-mail address matches the one registered at https://git.eclipse.org/r/#/settings/contact
    • To view the local e-mail address, do git config user.email. An empty result means the e-mail address has not been set yet.
    • To change the local e-mail address, do git config --global user.email [your email address here]
    • In the same manner, you can view and change your committer name using the user.name environment variable.
  5. To ensure correct handling of line endings when using Windows, please use the following git configs: core.autocrlf=true and core.filemode=false. If you have dirty projects due to Windows line endings, try a hard reset after setting the config.
  6. In Eclipse, clone the Henshin repository using one of the URLs (git, http, ssh) given at the repository website. We recommend the following workflow. If relevant, see below for a frequent error related to push rights.
    • For cloning the initial state of the repo, use the (read-only) GIT repository URL. Cloning the entire Repo via the SSH URL may lead to timeouts.
    • After cloning, change the repository location to the SSH repository URL (do git remote set-url origin <gerrit-url>, or follow the eGit instructions). Don't forget to substitute user_id in the URL by your actual Gerrit username, which can be found here.
  7. In the Git perspective, open the Repository: Remotes -> Right click on origin -> Gerrit Configuration... -> Finish.
  8. Follow the steps outlined in the next section.

After pushing a change, a corresponding entry on Gerrit has been created. Please invite (a subset of) the other committers as reviewers, doing this for all changes.

Frequent problem: no push rights

A frequent error message is:

Repository https://username@git.eclipse.org/r/henshin/org.eclipse.emft.henshin
prohibited by Gerrit: not permitted: update
error: branch refs/heads/master:
To push into this reference you need 'Push' rights.
User: username
Contact an administrator to fix the permissions."

This error message occurs if you're pushing to one of the read-only repository URLs. Please follow the instructions above, especially the part about changing the repository location.

Importing projects into your workspace and resolving dependencies

Henshin's codebase is divided into several plug-in projects with different responsibilies, for example:

  • Plug-in org.eclipse.emf.henshin.model: The meta-model
  • Plug-in org.eclipse.emf.henshin.diagram: The graphical editor
  • Plug-in org.eclipse.emf.henshin.interpreter: The interpeter
  • Plug-ins org.eclipse.emf.henshin.{edit,editor}: The tree-based editor


All plug-in projects are contained in the plugins folder in the root directory of our Git repo. Import the plug-ins you want to work on as Eclipse projects into your workspace. Depending on your selection, you may encounter various build errors. To resolve them, install dependencies as necessary. The provided links refer to update sites and cannot be opened in the browser. Use them to install the dependencies in Eclipse via Help -> Install New Software.

  • Papyrus for UML: needed for org.eclipse.emf.henshin.diagram. In the update site, find Papyrus in the Modeling category, or by using the filter. Papyrus provides some legacy components of GMF Tooling that are required by Henshin's GMF-based diagram editor.
  • Maven Integration for Eclipse: needed for org.eclipse.emf.henshin.giraph.
  • Eclipse Xtext: needed for org.eclipse.emf.henshin.text projects. On further build errors, trigger the Xtext generation process: navigate to org.eclipse.emf.henshin.text -> GenerateHenshin_text.mwe2, right click and do Run As -> MWE2 Workflow.
  • QVT Operational: needed for org.eclipse.emf.henshin.text.transformation. Navigate to the Metamodel Mappings: right click the project org.eclipse.emf.henshin.text.transformation -> Properties -> Metamodel Mappings. There add mappings for org.eclipse.emf.henshin.model/model/henshin.ecore and org.eclipse.emf.henshin.text/model/generated/Henshin_text.ecore: Add -> Browse -> navigate to .ecore-file.
  • EMF Compare: needed for org.eclipse.emf.henshin.interpreter.ui, org.eclipse.emf.henshin.multicda.cpa and org.eclipse.emf.henshin.text.transformation.tests.
  • AGG Runtime: needed for org.eclipse.emf.henshin.multicda.cpa. During installation filter for AGG Runtime to find the package.


To resolve further build errors in org.eclipse.emf.henshin.adapters.xtext right click the project -> Properties -> Resource and set the text file encoding to Other: UTF-8.

Back to the top