Difference between revisions of "ETrice/Development/Repository"

From Eclipsepedia

Jump to: navigation, search
(Steps to get up and running with Gerrit)
(Steps to get up and running with Gerrit)
(19 intermediate revisions by 3 users not shown)
Line 4: Line 4:
 
* General: complete online version of the ProGIT book: http://progit.org/book/
 
* General: complete online version of the ProGIT book: http://progit.org/book/
 
* Git@Eclipse: http://wiki.eclipse.org/Git
 
* Git@Eclipse: http://wiki.eclipse.org/Git
 +
* Git workflow recommendations: http://wiki.eclipse.org/Platform-releng/Git_Workflows
 
* For committers: http://wiki.eclipse.org/Git_for_Committers
 
* For committers: http://wiki.eclipse.org/Git_for_Committers
 
* You can directly get Web access to git repositories: http://git.eclipse.org/
 
* You can directly get Web access to git repositories: http://git.eclipse.org/
Line 15: Line 16:
 
*** Linux: Checkout as is, commit Unix-style line endings
 
*** Linux: Checkout as is, commit Unix-style line endings
 
* install EGit (update site): http://download.eclipse.org/egit/updates
 
* install EGit (update site): http://download.eclipse.org/egit/updates
 
+
** Line Endings for EGit in Eclipse: Be aware that the global settings of the command line version of git might be different from the global EGit settings: (Perspective Git Repository Exploring -> <Context Menu on Repo Location> Open Properties View -> Global Configuration -> Edit ):
 +
*** Windows: core.autocrlf = true
 +
*** Linux: core.autocrlf = input
 +
* Encoding in Eclipse (Window -> Preferences -> Workspace -> Text File Encoding)
 +
** Windows: Default (Cp1252)
 +
** Linux: Other -> ISO-8859-1
  
 
== Clone eTrice Repository ==
 
== Clone eTrice Repository ==
Line 51: Line 57:
 
* [https://git.eclipse.org/r/Documentation/index.html Gerrit Documentation]
 
* [https://git.eclipse.org/r/Documentation/index.html Gerrit Documentation]
 
* [[Gerrit|Gerrit Wiki Page]]
 
* [[Gerrit|Gerrit Wiki Page]]
 +
* [http://qt-project.org/wiki/Gerrit-Introduction Introduction to Gerrit] (by the Qt project)
  
 
=== Steps to get up and running with Gerrit ===
 
=== Steps to get up and running with Gerrit ===
Line 56: Line 63:
 
* get an Eclipse Bugzilla account
 
* get an Eclipse Bugzilla account
 
* get your user name from Gerrit (check the [https://git.eclipse.org/r/#/settings/ Gerrit settings])
 
* get your user name from Gerrit (check the [https://git.eclipse.org/r/#/settings/ Gerrit settings])
* upload an ssh key to Gerrit ([http://wiki.eclipse.org/Gerrit#Git_over_SSH see how])  
+
* upload an ssh key to Gerrit ([http://wiki.eclipse.org/Gerrit#Git_over_SSH see how])
 +
** make sure your ssh key resides in ~/.ssh (on Windows 7 this is typically /c/Users/<user name>/.ssh)
 +
** check in the ssh2 preferences of Eclipse the correct directory is set (e.g. /c/Users/<user name>/.ssh)
 +
** to avoid problems you should use the standard names for your key files (id_rsa and id_rsa.pub)
 
* if you do not already have a clone of the eTrice repository
 
* if you do not already have a clone of the eTrice repository
 
** use EGit or the command line client to clone from ssh://<your Gerrit user name>@git.eclipse.org:29418/etrice/org.eclipse.etrice.git
 
** use EGit or the command line client to clone from ssh://<your Gerrit user name>@git.eclipse.org:29418/etrice/org.eclipse.etrice.git
 
* if you have problems authenticating with Gerrit over Git it may help to <code>ssh -p 29418 <your Gerrit user name>@git.eclipse.org</code> once
 
* if you have problems authenticating with Gerrit over Git it may help to <code>ssh -p 29418 <your Gerrit user name>@git.eclipse.org</code> once
 +
** you can use the Git Bash that comes with the commandline GIT
 +
** make sure the working directory (~) is the same as for eclipse (/c/Users/<user name>)
 
* configure a remote for Gerrit reviews in your repository
 
* configure a remote for Gerrit reviews in your repository
 
** use the context menu of the Git Repositories View to Open Properties View
 
** use the context menu of the Git Repositories View to Open Properties View
 
** in the Properties View push the Edit icon in the upper right corner
 
** in the Properties View push the Edit icon in the upper right corner
** create a new entry remote.review.url with value ssh://<your Gerrit user name>@git.eclipse.org:29418/etrice/org.eclipse.etrice.git
+
** create new entries:
** create a new entry remote.review.push with value HEAD:refs/for/master
+
*** create a new entry '''remote.review.url''' with value '''ssh://<your Gerrit user name>@git.eclipse.org:29418/etrice/org.eclipse.etrice.git'''
 +
*** create a new entry '''remote.review.push''' with value '''HEAD:refs/for/master'''
 +
** '''Note for committers''': to bypass the review and push directly to the repository you can add another two entries in the properties of your repository:
 +
*** create a new entry '''remote.bypass.url''' with value '''ssh://<your Gerrit user name>@git.eclipse.org:29418/etrice/org.eclipse.etrice.git'''
 +
*** create a new entry '''remote.bypass.push''' with value '''HEAD:refs/heads/master'''
 +
** note :- for juno entry remote.review.push should have value HEAD:refs/for/juno (Only if you are working on juno branch)
 +
** set the property gerrit.createchangeid to true either in your repository or globally (details can be found [[EGit/User_Guide#Commit_Message | here]])
 +
*** Note: the Change-Id will be 0 and only be set to the real value on submit
  
 
Now you can commit your changes as usual to your local Git repository.
 
Now you can commit your changes as usual to your local Git repository.
Line 73: Line 92:
 
When everything is alright the committer may submit the changes to the eTrice Git repository.
 
When everything is alright the committer may submit the changes to the eTrice Git repository.
  
'''Note for committers''': to bypass the review and push directly to the repository you can add another two entries in the properties of your repository
+
=== Use branches when working with Gerrit ===
* create a new entry remote.bypass.url with value ssh://<your Gerrit user name>@git.eclipse.org:29418/etrice/org.eclipse.etrice.git
+
 
* create a new entry remote.bypass.push with value HEAD:refs/heads/master
+
* switch to a newly created (local) branch in your Git repository with an appropriate name, say 'mywork'
 +
* as long as you work on your local branch you are shielded against changes on the remote master branch. However, before you push you should pull the master branch and merge the changes into your local mywork branch
 +
* when you are ready to push you push your branch to Gerrit with ref HEAD:refs/for/master/mywork (this will create a so called topic branch in Gerrit)
 +
 
 +
=== Proper handling of Gerrit's Change Id ===
 +
 
 +
* Create a new change
 +
** If this is the first time it has seen the Change-Id mentioned in the commit message, Gerrit will create a new change for review.
 +
* Update an existing change
 +
** If Gerrit has seen this Change-Id before, but has not yet seen this new commit object, Gerrit will add the new commit as a new patch set on the existing change.
 +
 
 +
=== Squashing Changes ===
 +
 
 +
Here is an article how Git can merge several commits into one
 +
 
 +
http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html
 +
 
 +
=== Integrating a contribution ===
 +
 
 +
The patch has to be IP clean and it should be checked if a CQ is necessary!
 +
 
 +
If Gerrit isn't able to merge the patch (e.g. if prerequisites lead to conflicts) a committer can merge the patch locally to his master branch (make sure to have branch.master.rebase=true) and check that in. The history will show all the commits of the contributor.
 +
Since also the bypass uses Gerrit's interface Gerrit will mark the corresponding patches as merged.
 +
 
 +
=== Create a patch ===
 +
 
 +
For the CQ diff files of the patches have to be created and attached.
 +
 
 +
This can be done as follows:
 +
* <code>git log  --author=.*contributor_name.* --parents --oneline</code>
 +
** creates a compact list of the contributor's commits with two IDs (commit+parent) for regular commits or three IDs (commit+2 parents) for merges
 +
* <code>git format-patch --stdout 28fda9c..537d59a > patch_1.txt</code>
 +
** as IDs use the parent ID as first and the parent ID as second ID of the range
  
 
== Create a Patch via Git Gui==
 
== Create a Patch via Git Gui==

Revision as of 06:37, 20 December 2012

Contents

Git and eTrice

For eTrice we are using the Git-Repository from eclipse. For those people, who are not so familiar with Git, this chapter will give a step by step introduction.

Git in general and Git at Eclipse

After installation of EGit in Eclipse, you can look up "Git for Eclipse Users" in the EGit Documentation.

Installations on your computer

  • download git: http://git-scm.com/download
    • e.g. for Windows: Git-1.7.3.1-preview20101002.exe
    • Line Endings:
      • Windows: check out Windows-style, commit Unix-style line endings
      • Linux: Checkout as is, commit Unix-style line endings
  • install EGit (update site): http://download.eclipse.org/egit/updates
    • Line Endings for EGit in Eclipse: Be aware that the global settings of the command line version of git might be different from the global EGit settings: (Perspective Git Repository Exploring -> <Context Menu on Repo Location> Open Properties View -> Global Configuration -> Edit ):
      • Windows: core.autocrlf = true
      • Linux: core.autocrlf = input
  • Encoding in Eclipse (Window -> Preferences -> Workspace -> Text File Encoding)
    • Windows: Default (Cp1252)
    • Linux: Other -> ISO-8859-1

Clone eTrice Repository

Configuration

IMPORTANT: execute in shell or git shell:

  • git config --global user.email <your email address>
  • git config --global user.name "<your user name>"

pull/push (only for committers)

  • ssh: git clone ssh://<your commiter name>@git.eclipse.org/gitroot/etrice/org.eclipse.etrice.git
  • https: git clone https://<your commiter name>@git.eclipse.org/gitroot/etrice/org.eclipse.etrice.git

only pull

Use EGit

  • create empty workspace
  • open view "Git Repositories" or perspective "Git Repository Exploring"
  • add repository path of your local git repository you cloned before
  • contextmenu on repository: "Import Projects..."
  • Next >
  • Select All + Finish

Gerrit

Gerrit is a Code Review system for Git. Such a system is hosted by Eclipse.

The eTrice project enabled their Git repository for Gerrit. Committers can bypass Gerrit while Contributers have to use the reviewing system of Gerrit for their contributions.

Here is a selection of useful links that everybody should read:

Steps to get up and running with Gerrit

  • get an Eclipse Bugzilla account
  • get your user name from Gerrit (check the Gerrit settings)
  • upload an ssh key to Gerrit (see how)
    • make sure your ssh key resides in ~/.ssh (on Windows 7 this is typically /c/Users/<user name>/.ssh)
    • check in the ssh2 preferences of Eclipse the correct directory is set (e.g. /c/Users/<user name>/.ssh)
    • to avoid problems you should use the standard names for your key files (id_rsa and id_rsa.pub)
  • if you do not already have a clone of the eTrice repository
    • use EGit or the command line client to clone from ssh://<your Gerrit user name>@git.eclipse.org:29418/etrice/org.eclipse.etrice.git
  • if you have problems authenticating with Gerrit over Git it may help to ssh -p 29418 <your Gerrit user name>@git.eclipse.org once
    • you can use the Git Bash that comes with the commandline GIT
    • make sure the working directory (~) is the same as for eclipse (/c/Users/<user name>)
  • configure a remote for Gerrit reviews in your repository
    • use the context menu of the Git Repositories View to Open Properties View
    • in the Properties View push the Edit icon in the upper right corner
    • create new entries:
      • create a new entry remote.review.url with value ssh://<your Gerrit user name>@git.eclipse.org:29418/etrice/org.eclipse.etrice.git
      • create a new entry remote.review.push with value HEAD:refs/for/master
    • Note for committers: to bypass the review and push directly to the repository you can add another two entries in the properties of your repository:
      • create a new entry remote.bypass.url with value ssh://<your Gerrit user name>@git.eclipse.org:29418/etrice/org.eclipse.etrice.git
      • create a new entry remote.bypass.push with value HEAD:refs/heads/master
    • note :- for juno entry remote.review.push should have value HEAD:refs/for/juno (Only if you are working on juno branch)
    • set the property gerrit.createchangeid to true either in your repository or globally (details can be found here)
      • Note: the Change-Id will be 0 and only be set to the real value on submit

Now you can commit your changes as usual to your local Git repository.

When everything is ready to push you can use EGit to push to the reviewing system (use the review remote). Gerrit will create a new change which can be reviewed and verified by a committer. Gerrit allows the committer to leave comments in the source code diff which will help to improve the code.

When everything is alright the committer may submit the changes to the eTrice Git repository.

Use branches when working with Gerrit

  • switch to a newly created (local) branch in your Git repository with an appropriate name, say 'mywork'
  • as long as you work on your local branch you are shielded against changes on the remote master branch. However, before you push you should pull the master branch and merge the changes into your local mywork branch
  • when you are ready to push you push your branch to Gerrit with ref HEAD:refs/for/master/mywork (this will create a so called topic branch in Gerrit)

Proper handling of Gerrit's Change Id

  • Create a new change
    • If this is the first time it has seen the Change-Id mentioned in the commit message, Gerrit will create a new change for review.
  • Update an existing change
    • If Gerrit has seen this Change-Id before, but has not yet seen this new commit object, Gerrit will add the new commit as a new patch set on the existing change.

Squashing Changes

Here is an article how Git can merge several commits into one

http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html

Integrating a contribution

The patch has to be IP clean and it should be checked if a CQ is necessary!

If Gerrit isn't able to merge the patch (e.g. if prerequisites lead to conflicts) a committer can merge the patch locally to his master branch (make sure to have branch.master.rebase=true) and check that in. The history will show all the commits of the contributor. Since also the bypass uses Gerrit's interface Gerrit will mark the corresponding patches as merged.

Create a patch

For the CQ diff files of the patches have to be created and attached.

This can be done as follows:

  • git log --author=.*contributor_name.* --parents --oneline
    • creates a compact list of the contributor's commits with two IDs (commit+parent) for regular commits or three IDs (commit+2 parents) for merges
  • git format-patch --stdout 28fda9c..537d59a > patch_1.txt
    • as IDs use the parent ID as first and the parent ID as second ID of the range

Create a Patch via Git Gui

  • open the Git Gui from your windows menu
  • open your "local Git Repositoriy"
  • from the main menu select "Projektarchiv" => "Historie von >>master<< darstellen"
  • in the new window the latest master version must be selected (blue)
  • right click on "lokale Änderungen"
  • in the contextmenu select "Patch erstellen"

Apply a Patch

We assume the patch was created as described above.

  • in the context menu of the Package Explorer go to Team > Apply patch...
  • in the wizard select File and locate the patch file
  • select 'Apply the patch to the workspace root'
  • set leading path segments to 2
  • check the result and Finish

Checkout a previous revision

Inspect the log and determine the commit id you want to change to. Then git checkout this:

 $ git checkout 2eb90f4643fd425f77de2b88753a86416cda0166
 Note: checking out '2eb90f4643fd425f77de2b88753a86416cda0166'.
 
You are in 'detached HEAD' state. You can look around, make experimental changes and commit them, and you can discard any commits you make in this state without impacting any branches by performing another checkout.
If you want to create a new branch to retain commits you create, you may do so (now or later) by using -b with the checkout command again. Example:
git checkout -b new_branch_name
HEAD is now at 2eb90f4... ui.structure: during creation take position as midpoint of new interface item. Adjusted PopulateDiagramCommand accordingly.

working with branches

creating a local branch

pushing a local branch

creating a remote tracking branch

pulling for remote tracking branches

If you often merge with the same branch, you may want to use something like the following in your configuration file:

   [branch "before_indigo"]
   remote = <nickname>
   merge = <remote-ref>
   [remote "<nickname>"]
   url = <url>
   fetch = <refspec>

With EGit the configuration can be accesses from the Git Repositories View context menu > Open Properties View The Properties View displays the current configuration and offers an Edit button in the upper left corner.

Here is an example of a pull configuration for a remote tracking branch:
GitConfig.jpg

Using the eTrice github clone

According to https://bugs.eclipse.org/bugs/show_bug.cgi?id=332970 Eclipse projects with git repositories (and correct metadata set) are mirrored to github.

And so is eTrice: https://github.com/eclipse/etrice

Here are some slides explaining how github is accessed using EGit: http://www.slideshare.net/loianeg/using-the-egit-eclipse-plugin-with-git-hub-2578587

Any github user can fork an existing github repository. This facilitates collaborating with contributors which have no commit rights.

See also the Wiki page on Git contributions.

TODO: typical workflow...

Some hints to create Documentation

Location of Documentation

- ETrice Documentation will be put to org.eclipse.etrice.doc

- numbering of chapters is 000-xxx, 005-yyy, 010-zzz, 015... to have room for inject some chapters

- images (put to the folder images) should have the same numbering according to the chapters

- within the etrice-index.txt document the ordering of the chapters will be done. This file will be used from the build prozess to collect all single .textile files to produce the complete Doku.

- build prozess will be started from the external tool menu => "build-etrice-doc". (you must have internet access during production of the docu)


Within the .textile file

- with F1 you can get a list of the formating strings

- some formating options does not work well for all document types e.g. __italic__ does not work in the pdf file if the string contains "_". => therefore, for names which reference a concrete model name (shown in a picture or code block) use: "??This_is_my_name??" == citation

Images

- use IrfanView to create screen shots (everything on board what you need)

- use the png format to save pictures (i had never problems with that)

- pictures should not be larger than 640*480 pixels. Otherwise they will cause problems in the PDF file. IrfanView: Ctrl+r => resize image

- to sharpen the images, use IrfanView: Image=>sharpen to create perfect screen shots.

Steps to change to Indigo

  • download and install eclipse Modeling for Win32

"http://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/indigo/R/eclipse-modeling-indigo-win32.zip"

  • install Xtext from

http://www.eclipse.org/Xtext/download/ (drag and drop the install icon to your eclipse toolbar)

  • install Egit, Subversive and Graphiti via the update site from indogo

http://download.eclipse.org/releases/indigo (for Subversive use the Connector Native JavaHL 1.6.12)

  • download the target configuration "target-indigo-2011-06-29" from ftp.protos.de and copy it to your target path. To get the credits for the protos ftp server, please contact ts@protos.de.
  • in preferences=>Run/Debug=>String Substitution make sure that the variable "eTriceTargetInstallationPath" is set to your target path. (create the variable if not existing)
  • in the preferences=>plug in development=>target configuration, make sure that the "eTrice development" target is selected
  • sometimes it is necessary to update the plug in list (IOExtensions cannot be resolved)

=> windows=>preferences=>pulg in development=> target configuration (select the "running configuration" and apply it, select the "eTrice development" target again and apply it) (if somebody knows a smarter way to update the plug in list, please change this wiki)