Difference between revisions of "MDT/OCL/Dev/EGit"

From Eclipsepedia

< MDT‎ | OCL
Jump to: navigation, search
(Commit to Branch)
m
 
(34 intermediate revisions by one user not shown)
Line 1: Line 1:
The Eclipse OCL code is maintained in a GIT repository which is used by [[#Clone Repository | Clone Repository]]. This repository is used in a traditional 'client'/'server' fashion, even though GIT treats all users as peers. The definitive state is on the 'server' at git://git.eclipse.org/gitroot/mdt/org.eclipse.ocl.git. Individual committers establish 'client' clones of the 'server' so that for committers, the definitive development stream is at '''origin/master''' and each committer's '''master''' is a branch of '''origin/master'''. A definitive maintenance stream is at for instance '''origin/R3_1'''.
+
The capabilities of [[EGit]] are described in [[EGit/User Guide]]. The documentation here is complementary, it describes how the Eclipse OCL committers use EGit to satisfy typical use cases. The first of these is obviously [[#Clone Repository | Clone Repository]]. Thereafter the [[#Major Change | Major Change]] and [[#Minor Change | Minor Change]] workflows cover typical developments.
  
The capabilities of [[EGit]] are described at [[EGit/User Guide]]. The documentation here is complementary, it describes how the committers use EGit to satisfy typical use cases.
+
==Principles==
  
== Complete Use Cases ==
+
The recommended workflows are governed by the following principles:
  
=== Develop a Non-trivial Change ===
+
* commits to upstream release branches are final
 +
** the commit history may be extended
 +
** the commit history must not be changed/interleaved
 +
* pulling from upstream is easy
  
The normal evolution of the project code involves a non-trivial change that may take a few days or weeks to develop, may need review by another committer and may occur concurrently with some other change.
+
Generally an upstream branch is more definitive than a downstream branch; therefore:
  
A Bugzilla describes the intended change and supports communication regarding the progress of the change.
+
# NEVER rebase a more definitive branch onto a less definitive branch
 +
# ALWAYS rebase onto an more definitive branch before merging a less definitive branch into it
 +
# ALWAYS create a local development branch from an upstream branch
  
The change is developed in a branch whose name starts with '''bug/''nnnnnn''''' where ''nnnnnn'' is the Bugzilla number. A short description may follow.
+
==Branches==
  
* [[#Discard Old Work | Discard Old Work]] to facilitate doing something new
+
The Eclipse OCL code is maintained in a GIT repository which is used in a traditional 'client'/'server' fashion, even though GIT treats all repositories as peers. The definitive state is on the upstream 'server' at git://git.eclipse.org/gitroot/mdt/org.eclipse.ocl.git. Individual committers establish local 'client' clones of the upstream 'server' so that for committers, the definitive development stream is at '''origin/master''' and each committer's '''master''' is a branch of '''origin/master'''.
* [[#Create New Branch | Create New Branch]] or [[#Switch to Local Branch | Switch to Local Branch]] or [[#Switch to Remote Branch | Switch to Remote Branch]]
+
* Develop and test changes
+
* [[#Review Changes | Review Changes]] prior to commit
+
* [[#Commit to Branch | Commit to Branch]]
+
* [[#Push to Upstream | Push to Upstream]] to create a backup at Eclipse or to publish to other committers  
+
* [[#Create Patch | Create Patch]] to attach to Bugzilla for review
+
* [[#Request Review | Request Review]]
+
* [[#Rebase Branch onto origin/master | Rebase Branch onto '''origin/master''']] to synchronize with concurrent development
+
* [[#Review Changes | Review Changes]] prior to merge
+
* [[#Merge Branch onto origin/master | Merge Branch onto '''origin/master''']] to commit to the development stream
+
* [[#Merge Branch onto Another Branch | Merge Branch onto Another Branch]] such as a maintenance branch
+
* [[#Archive Old Branch | Archive Old Branch]] to prune the EGit displays
+
  
=== Develop a Trivial Change ===
+
===Release Branches===
 +
 
 +
The '''master''' release branch is the development stream for the next Eclipse OCL release.
 +
 
 +
The '''maintenance/R''major''_''minor''''' release branch is the maintenance stream for the Eclipse OCL ''major''.''minor''.* service releases.
 +
 
 +
===Topic Branches===
 +
 
 +
Very simple changes may be developed directly in a release branch. Other changes are developed in a topic branch, which has an associated Bugzilla to describe the intended change and to support communication regarding the progress of the change.
 +
 
 +
An active topic branch is named '''bug/''xxxxxx'' ''description''''' where ''xxxxx'' is the Bugzilla number and ''description'' is an optional description to make the Remote Tracking lists in the [[EGit/User_Guide#Structure_of_the_Git_Repositories_View | Repositores View]] more meaningful.
 +
 
 +
A completed topic branch is renamed to '''archive/''xxxxxx'''''.
 +
 
 +
All commit descriptions for a topic branch are prefixed by '''[''xxxxxx'']'''. This facilitates interpretation of the GIT history in a variety of contexts such as blame annotations, and [https://github.com/eclipse/ocl/network Github networks] that present just the short description.
 +
 
 +
== Git Background ==
 +
 
 +
=== Git Files ===
 +
 
 +
GIT provides many locations in which distinct versions of a file may be stored.
 +
 
 +
* The Local Repository contains many branches one of which is the Local Branch for the CheckedOut Branch
 +
** the HEAD of the Local Branch is the committed state of the file
 +
** the staged copy in the Index is ready for a commit
 +
** the tracked copies in the Working Tree may be modified
 +
 
 +
* The Upstream Repository contains many branches one of which is the Upstream Branch
 +
** the HEAD of the Upstream Branch is the definitive released version
 +
 
 +
* The Eclipse Workspace comprises
 +
** the tracked files in the Working Tree
 +
** untracked files not in the Working Tree
 +
** Eclipse History may maintain multiple copies
 +
 
 +
[[Image:GitFiles.png|GIT File locations]]
 +
 
 +
The actions that migrate file contents between the various locations are depicted below, with round blobs
 +
indicating where an action may start, and arrows indicating where it may end.
 +
 
 +
== Workflows ==
 +
 
 +
===Minor Change===
  
 
Very simple changes that do not require review, or must be performed in a hurry may be performed directly on the local master branch.
 
Very simple changes that do not require review, or must be performed in a hurry may be performed directly on the local master branch.
  
* [[#Discard Old Work | Discard Old Work]] to facilitate doing something new
+
* Optionally [[#Discard Old Work | Discard Old Work]] to facilitate doing something new
* [[#Switch to Local Master| Switch to local/'''master''']]
+
* [[#Fetch from Upstream | Fetch from Upstream]] to update your local repository
* [[#Pull from Upstream | Pull from Upstream]] to synchronize with development stream
+
* [[#Switch to Local Branch| Switch to local '''master''']]
 +
* [[#Fetch and Rebase Branch | Fetch and Rebase local '''master''' onto '''origin/master''']] to ensure master is current
 
* Develop and test changes
 
* Develop and test changes
* [[#Review Changes | Review Changes]] prior to commit
+
* Optionally [[#Review Workspace Changes | Review Workspace Changes]] prior to commit
* [[#Commit to Branch | Commit to local/'''master''']]
+
* [[#Commit to Branch | Commit to local '''master''']]
* [[#Merge Branch onto origin/master | Merge local/'''master''' onto '''origin/master''']] to commit to the development stream
+
* Optionally [[#Review Branch Changes | Review Branch Changes]] prior to merge
 +
* [[#Fetch and Rebase Branch | Fetch and Rebase local '''master''' onto '''origin/master''']] to ensure master is current again
 +
* [[#Push to Upstream | Push to Upstream]] to commit local '''master''' to '''origin/master''' release stream
 +
 
 +
===Major Change===
 +
 
 +
The normal evolution of the project code involves a non-trivial change that may take a few days or weeks to develop, may need review by another committer and may occur concurrently with some other change.
 +
 
 +
The change is developed in a topic branch whose name starts with '''bug/''nnnnnn''''' where ''nnnnnn'' is the Bugzilla number. A short description may follow.
 +
 
 +
* Optionally [[#Discard Old Work | Discard Old Work]] to facilitate doing something new
 +
* [[#Fetch from Upstream | Fetch from Upstream]] to update your local repository
 +
* [[#Create New Branch | Create New topic Branch]] or [[#Switch to Local Branch | Switch to Local topic Branch]]
 +
* Develop and test changes
 +
* Optionally [[#Review Workspace Changes | Review Workspace Changes]] prior to commit
 +
* [[#Commit to Branch | Commit to topic Branch]]
 +
* Optionally [[#Push to Upstream | Push to Upstream]] to create a backup at Eclipse or to publish to other committers
 +
* Optionally [[#Create Patch and Request Review | Create Patch and Request Review]]
 +
* [[#Switch to Local Branch | Switch to local '''master''']]
 +
* [[#Fetch and Rebase Branch | Fetch and Rebase local '''master''' onto '''origin/master''']] to ensure master is current
 +
* [[#Merge Branch onto local master | Merge topic Branch onto local '''master''']] to create updated local stream
 +
* Rerun tests
 +
* Optionally [[#Review Branch Changes | Review Branch Changes]] prior to merge
 +
* [[#Fetch and Rebase Branch | Fetch and Rebase local '''master''' onto '''origin/master''']] to ensure master is current again
 +
* [[#Push to Upstream | Push to Upstream]] to commit local '''master''' to '''origin/master''' release stream
 +
* Optionally Perform [[#Maintenance Change | Maintenance Change]] to change a maintenance stream too
 +
* Optionally [[#Archive Old Branch | Archive Old topic Branch]] to prune the EGit displays
 +
 
 +
===Maintenance Change===
 +
 
 +
Some changes to the master release stream may also be applied to a maintenance stream.
 +
 
 +
* Perform [[#Major Change | Major Change]] to the master release stream
 +
* [[#Create New Branch | Create local maintenance Branch]] or [[#Switch to Local Branch | Switch to local maintenance Branch]]
 +
* [[#Fetch and Rebase Branch | Fetch and Rebase local maintenance onto upstream maintenance]] to ensure local maintenance is current again
 +
* [[#Cherrypick Commits | Cherrypick Commits]] to update the maintenance branch
 +
* Redevelop and test changes
 +
* Optionally [[#Review Workspace Changes | Review Workspace Changes]] prior to commit
 +
* [[#Commit to Branch | Commit to local maintenance Branch]]
 +
* Optionally [[#Review Branch Changes | Review Branch Changes]] prior to merge
 +
* [[#Push to Upstream | Push to Upstream]] to commit local maintenance to upstream maintenance stream
  
== Partial Use Cases ==
+
== Use Cases ==
  
 
===Clone Repository===
 
===Clone Repository===
  
The Eclipse GIT repositories are accessed using SSH, so you if you want write access, you should first make sure that you have [[EGit/User_Guide#Eclipse_SSH_Configuration | SSH keys]]. Then you should use the Git Repositories View of the Git Repository Exploring perspective to [[EGit/User_Guide#Cloning_Remote_Repositories | Create a clone of the existing Git repository]] accessed at ssh://''committer-id''@git.eclipse.org/gitroot/mdt/org.eclipse.ocl.git. ''committer-id'' is your Eclipse committer name, typically comprising the first letter of your first name followed by your last name.
+
The Eclipse GIT repositories are accessed using SSH, so you if you want write access, you should first make sure that you have [[EGit/User_Guide#Eclipse_SSH_Configuration | SSH keys]]. The Windows->Preferences->General->Network Connections->SSH2->Key Management
 +
should be adequate to install keys; a shell login to eclipse.org is not be necessary.
 +
 
 +
Then you should use the Git Repositories View of the Git Repository Exploring perspective to [[EGit/User_Guide#Cloning_Remote_Repositories | Create a clone of the existing Git repository]] accessed at ssh://''committer-id''@git.eclipse.org/gitroot/mdt/org.eclipse.ocl.git. ''committer-id'' is your Eclipse committer name, typically comprising the first letter of your first name followed by your last name.
  
 
Creating the clone takes quite some time, perhaps five to ten minutes, not all of which has comforting progress indications. You can use a file explorer to watch the progress. A complete directory tree for each project appears late in the cloning process.
 
Creating the clone takes quite some time, perhaps five to ten minutes, not all of which has comforting progress indications. You can use a file explorer to watch the progress. A complete directory tree for each project appears late in the cloning process.
  
===Create New Branch===
+
Once you have a repository, it is recommended to [[EGit/User_Guide#Importing_projects | Import All Projects]] into your workspace. The initial configuration of the Git workspace was incorrect and some projects were moved, and one of those moves inadvertently occurred one folder up. Consequently the early history has some migrations that are problematic for Git and these may incorrectly suggest that your workspace is dirty when it is not. If you have all projects imported, you should at least see what the problems are.
  
[[EGit/User_Guide#Creating_a_New_Local_Branch | A new branch]] should almost always be created as a branch of '''origin/master''', since this gives a simple direct relationship to the development stream. If you use another branch such as local/'''master''' you create a branch of a branch and may encounter difficulties in synchronizing changes or exporting the branch to other repositories that may not be aware of all changes in your local/'''master'''.
+
===Fetch from Upstream===
 +
 
 +
It is important to [[EGit/User_Guide#Fetching_from_upstream | Fetch from Upstream]] regularly to ensure that concurrent changes are available in your local repository.
  
 
===Discard Old Work===
 
===Discard Old Work===
Line 55: Line 136:
 
EGit is very reluctant to allow you to lose work, so if your current workspace currently contains some experimental changes resulting perhaps from a review or newsgroup query, you must lose these changes before you can proceed.
 
EGit is very reluctant to allow you to lose work, so if your current workspace currently contains some experimental changes resulting perhaps from a review or newsgroup query, you must lose these changes before you can proceed.
  
Changes may be thrown away by Resetting to match some branch, possibly the current one, possibly '''origin/master''', the synchronizing the workspace, and overwriting to lose all changes.
+
Changes may be thrown away by [[EGit/User_Guide#Resetting_your_current_HEAD | Resetting hard]] to match some branch, possibly the current one, possibly '''origin/master'''.
 +
 
 +
If naive builders are in use, such as Acceleo's, the reset may trigger a rebuild that makes the workspace dirty again.It may therefore be necessary to disable builds, synchronize, and overwrite the rebuilt files to lose the changes.
 +
 
 +
===Create New Branch===
 +
 
 +
You may create a [[EGit/User_Guide#Creating_a_New_Local_Branch | new local branch]] in order to start development of some changes.
 +
This should almost always be created from an upstream branch, since this gives a simple direct relationship to the development stream. If you use another branch such as local '''master''' you create a branch of a branch and may encounter difficulties in synchronizing changes or exporting the branch to other repositories that may not be aware of all changes in your local '''master'''.
 +
 
 +
It is recommended to configure the pull stategy to rebase so that a Pull can be used to [[Fetch and Rebase Branch]].
 +
 
 +
If you want to continue development on a pre-existing upstream branch you should [[EGit/User_Guide#Checking_out_an_existing_Branch | Checkout an existing branch]]. This creates a local branch for which the remote branch is the upstream configuration, ensuring that Fetch and Push are useful.
 +
 
 +
If you want to continue development on a pre-existing local branch you should [[#Switch to Local Branch | switch to it]].
 +
 
 +
On no account check out a Remote Tracking branch directly. You may succeed in committing changes locally, but they will appear to get lost since they will not be synchronized with the remote branch that you have 'changed'.
  
 
===Switch to Local Branch===
 
===Switch to Local Branch===
  
===Switch to Remote Branch===
+
You may switch to a local topic branch in order to resume work on that topic.
 +
 
 +
You may switch to a local release branch in order to perform a very simple development directly on the release.
 +
 
 +
You should switch to a local release branch in order to merge the rebased development from a topic branch into an upstream release.
 +
 
 +
===Switch to Upstream Branch===
 +
 
 +
You should not normally switch to an upstream branch or tag since this creates a [[EGit/User_Guide#Fetching_a_change_from_a_Gerrit_Code_Review_Server | detached HEAD]]. Any changes that you make are easily lost and difficult to retrieve.
 +
 
 +
You may switch to an upstream branch to review it, but don't forget that changes will get lost.
 +
 
 +
===Review Workspace Changes===
  
If the remote branch is relatively new you may need to [[EGit/User_Guide#Fetching_from_upstream | Fetch from Upstream]] to update your list of Remote Tracking branches.
+
The changes awaiting commit may be displayed by [[EGit/User_Guide#Comparing_with_Branches_.28Synchronize.29 | Synchronize Workspace]]. This activates the [[EGit/User_Guide#Synchronize_View | Synchronize View]] in which comparisons can be reviewed.
  
Then select any Git project and [[EGit/User_Guide#Checking_out_an_existing_Branch | Switch to Remote Branch]]. The decoration on all projects should change to show that the selected branch is in use.
+
===Review Branch Changes===
  
===Review Changes===
+
The changes between a current branch and another can be displayed by [[EGit/User_Guide#Synchronizing_with_a_Branch_or_a_Tag | Synchronize]]. This activates the [[EGit/User_Guide#Synchronize_View | Synchronize View]] in which comparisons can be reviewed.
  
 
===Commit to Branch===
 
===Commit to Branch===
Line 71: Line 179:
 
Changes are committed to the current branch. They can be committed directly from the Package Explorer view, but this offers limited opportunity for review.
 
Changes are committed to the current branch. They can be committed directly from the Package Explorer view, but this offers limited opportunity for review.
  
It is recommended to Synchronize Workspace, so that all changes are displayed in the Synchronize View, allowing differences to be reviewed by double clicking files. The files to be committed may be selected and then committed.
+
It is recommended to [[EGit/User_Guide#Comparing_with_Branches_.28Synchronize.29 | Synchronize Workspace]], so that all changes are displayed in the [[EGit/User_Guide#Synchronize_View | Synchronize View]], allowing differences to be reviewed by double clicking files. The files to be committed may be selected and then committed.
  
 
Once all changes have been committed the Synchronize View should show no changes. Unfortunately the Synchronize View has limited understanding of '''.gitignore''' and so many spurious files suddenly show as needing a commit. It is currently necessary to return to the Package Explorer and resynchronize from there.
 
Once all changes have been committed the Synchronize View should show no changes. Unfortunately the Synchronize View has limited understanding of '''.gitignore''' and so many spurious files suddenly show as needing a commit. It is currently necessary to return to the Package Explorer and resynchronize from there.
Line 77: Line 185:
 
If naive builders are in use, such as Acceleo's, the commit may trigger a rebuild that then appears to show a need to commit further files. These files mark the workspace as dirty, preventing rebasing or switching. It may therefore be necessary to disable builds, resynchronize, and overwrite the rebuilt files to lose the changes.
 
If naive builders are in use, such as Acceleo's, the commit may trigger a rebuild that then appears to show a need to commit further files. These files mark the workspace as dirty, preventing rebasing or switching. It may therefore be necessary to disable builds, resynchronize, and overwrite the rebuilt files to lose the changes.
  
===Create Patch===
+
===Create Patch and Request Review===
  
===Request Review===
+
Patches are created by selecting a commit in the History View, so select the repository in the Git Repositories View and invoke Show in History. Then select the commit from which to create a patch.
  
===Rebase Branch onto origin/master===
+
TODO: Explain how to create a patch from A to B.
 +
 
 +
Attach the patch to the Bugzilla and set your email as the QA contact so that a Mylyn task searching for open bugs with an '@' in the QA contact will identify the patch as awaiting review.
 +
 
 +
===Fetch and Rebase Branch===
 +
 
 +
Before merging a change to upstream, you should minimize the opportunities for concurrency conflicts by [[EGit/User_Guide#Fetching_from_upstream | Fetching from Upstream]] to update your workspace and [[EGit/User_Guide#Starting_Rebase | Rebasing]] onto the upstream branch.
 +
 
 +
These two actions can be achieved by a [[EGit/User_Guide#Pulling_New_Changes_from_Upstream_Branch |Pull]] if you [[EGit/User_Guide#Branch_Creation_Dialog | configure your branch pull strategy]] to Rebase.
  
 
In order to merge concurrent changes from for instance '''origin/master''' you [[EGit/User_Guide#Starting_Rebase | Rebase]] onto the '''origin/master''' branch. This does not affect the '''origin/master''' branch.
 
In order to merge concurrent changes from for instance '''origin/master''' you [[EGit/User_Guide#Starting_Rebase | Rebase]] onto the '''origin/master''' branch. This does not affect the '''origin/master''' branch.
 +
 +
: Note that 'Rebase onto' refers to commit history rather than branch contents, so when branch A is rebased onto branch B, the commit history of branch A is changed to be the commit history of branch B with the residue of branch A onto of it. 'onto' does not suggest that the content of branch B is pasted onto branch A.
  
 
You cannot Rebase while your workspace has pending changes, so you must commit, or discard those before rebasing.
 
You cannot Rebase while your workspace has pending changes, so you must commit, or discard those before rebasing.
  
===Merge Branch onto origin/master===
+
===Merge Branch onto local master===
  
===Merge Branch onto Another Branch===
+
Once your changes are ready for incorporation into the development stream, have been tested and your development stream is rebased, you may [[EGit/User_Guide#Merging_a_branch_or_a_tag_into_the_current_branch | Merge]] the topic branch into the local '''master''' branch.
 +
 
 +
===Push to Upstream===
 +
 
 +
Once your changes have been tested in a local release branch such as '''master''', you may push upstream to incorporate those changes in the corresponding upstream release branch such as '''origin/master'''.
 +
 
 +
A simple [[EGit/User_Guide#Pushing_to_upstream | Push to Upstream]] pushes all local branches upstream, which may not be what you want, so you may want to do Team->Remote->Push... to control a [[EGit/User_Guide#Direct_Push | Direct Push]].
 +
 
 +
If concurrent changes have occurred, you must rebase to resolve the concurrency conflict.
 +
 
 +
===Cherrypick Commits===
 +
 
 +
When some commits developed for one stream, such as the master release stream, are also applicable to another stream, such as a maintenance stream, the commits may be reused by cherrypicking. After switching to the branch to be updated, [[EGit/User_Guide#Cherry_Picking | Cherrypick]] the required commits.
 +
 
 +
It is recommended to cherrypick one at a time in forward order; multiple commits can lead to spurious conflicts.
 +
 
 +
If conflicts arise they must be [[EGit/User_Guide#The_Real_World:_Rebase_Conflicts | Resolved]].
  
 
===Archive Old Branch===
 
===Archive Old Branch===
 +
 +
When the work of a topic branch has been resolved, the topic branch is renamed as '''archive/''xxxxxx''''' so that a hierarchical display of branches separates the active from resolved topic branches. GIT does not support direct operation on the upstream repository, so this rename is achieved by a (re-)creating the new '''archive/''xxxxxx''''' branch and deleting the old '''bug/''xxxxxx''''' branch.
 +
 +
You may archive many branches at once, provided you have an up-to-date local copy of each branch ready for pushing upstream again.
 +
 +
For each branch to archive, first [[#Switch to Local Branch | Switch to Local topic Branch]] or [[#Create New Branch | Create New local Branch]] and [[EGit/User_Guide#Pulling_New_Changes_from_Upstream_Branch |Pull]] to update it. Then from the EGit repositories view, [[EGit/User_Guide#Push_Wizard | Push...]] and add a push specification to push '''bug/''xxxxxx''''' as '''archive/''xxxxxx''''', and another to delete '''bug/''xxxxxx'''''.
 +
 +
This upstream change only partially propagates to other repositories, for which a [[EGit/User_Guide#Fetching_from_upstream | Fetch from Upstream]] will show the new '''archive/''xxxxxx''''', but will not prune the old '''bug/''xxxxxx''''', so branches in the Remote Tracking list may be [[EGit/User_Guide#Deleting_Branch | deleted]] to at least remove any matches for archived branches. It is safe to delete remote tracking branches speculatively, since they will reappear with a [[EGit/User_Guide#Fetching_from_upstream | Fetch from Upstream]].
 +
 +
[[Category:Git]]

Latest revision as of 16:09, 18 August 2011

The capabilities of EGit are described in EGit/User Guide. The documentation here is complementary, it describes how the Eclipse OCL committers use EGit to satisfy typical use cases. The first of these is obviously Clone Repository. Thereafter the Major Change and Minor Change workflows cover typical developments.

Contents

[edit] Principles

The recommended workflows are governed by the following principles:

  • commits to upstream release branches are final
    • the commit history may be extended
    • the commit history must not be changed/interleaved
  • pulling from upstream is easy

Generally an upstream branch is more definitive than a downstream branch; therefore:

  1. NEVER rebase a more definitive branch onto a less definitive branch
  2. ALWAYS rebase onto an more definitive branch before merging a less definitive branch into it
  3. ALWAYS create a local development branch from an upstream branch

[edit] Branches

The Eclipse OCL code is maintained in a GIT repository which is used in a traditional 'client'/'server' fashion, even though GIT treats all repositories as peers. The definitive state is on the upstream 'server' at git://git.eclipse.org/gitroot/mdt/org.eclipse.ocl.git. Individual committers establish local 'client' clones of the upstream 'server' so that for committers, the definitive development stream is at origin/master and each committer's master is a branch of origin/master.

[edit] Release Branches

The master release branch is the development stream for the next Eclipse OCL release.

The maintenance/Rmajor_minor release branch is the maintenance stream for the Eclipse OCL major.minor.* service releases.

[edit] Topic Branches

Very simple changes may be developed directly in a release branch. Other changes are developed in a topic branch, which has an associated Bugzilla to describe the intended change and to support communication regarding the progress of the change.

An active topic branch is named bug/xxxxxx description where xxxxx is the Bugzilla number and description is an optional description to make the Remote Tracking lists in the Repositores View more meaningful.

A completed topic branch is renamed to archive/xxxxxx.

All commit descriptions for a topic branch are prefixed by [xxxxxx]. This facilitates interpretation of the GIT history in a variety of contexts such as blame annotations, and Github networks that present just the short description.

[edit] Git Background

[edit] Git Files

GIT provides many locations in which distinct versions of a file may be stored.

  • The Local Repository contains many branches one of which is the Local Branch for the CheckedOut Branch
    • the HEAD of the Local Branch is the committed state of the file
    • the staged copy in the Index is ready for a commit
    • the tracked copies in the Working Tree may be modified
  • The Upstream Repository contains many branches one of which is the Upstream Branch
    • the HEAD of the Upstream Branch is the definitive released version
  • The Eclipse Workspace comprises
    • the tracked files in the Working Tree
    • untracked files not in the Working Tree
    • Eclipse History may maintain multiple copies

GIT File locations

The actions that migrate file contents between the various locations are depicted below, with round blobs indicating where an action may start, and arrows indicating where it may end.

[edit] Workflows

[edit] Minor Change

Very simple changes that do not require review, or must be performed in a hurry may be performed directly on the local master branch.

[edit] Major Change

The normal evolution of the project code involves a non-trivial change that may take a few days or weeks to develop, may need review by another committer and may occur concurrently with some other change.

The change is developed in a topic branch whose name starts with bug/nnnnnn where nnnnnn is the Bugzilla number. A short description may follow.

[edit] Maintenance Change

Some changes to the master release stream may also be applied to a maintenance stream.

[edit] Use Cases

[edit] Clone Repository

The Eclipse GIT repositories are accessed using SSH, so you if you want write access, you should first make sure that you have SSH keys. The Windows->Preferences->General->Network Connections->SSH2->Key Management should be adequate to install keys; a shell login to eclipse.org is not be necessary.

Then you should use the Git Repositories View of the Git Repository Exploring perspective to Create a clone of the existing Git repository accessed at ssh://committer-id@git.eclipse.org/gitroot/mdt/org.eclipse.ocl.git. committer-id is your Eclipse committer name, typically comprising the first letter of your first name followed by your last name.

Creating the clone takes quite some time, perhaps five to ten minutes, not all of which has comforting progress indications. You can use a file explorer to watch the progress. A complete directory tree for each project appears late in the cloning process.

Once you have a repository, it is recommended to Import All Projects into your workspace. The initial configuration of the Git workspace was incorrect and some projects were moved, and one of those moves inadvertently occurred one folder up. Consequently the early history has some migrations that are problematic for Git and these may incorrectly suggest that your workspace is dirty when it is not. If you have all projects imported, you should at least see what the problems are.

[edit] Fetch from Upstream

It is important to Fetch from Upstream regularly to ensure that concurrent changes are available in your local repository.

[edit] Discard Old Work

EGit is very reluctant to allow you to lose work, so if your current workspace currently contains some experimental changes resulting perhaps from a review or newsgroup query, you must lose these changes before you can proceed.

Changes may be thrown away by Resetting hard to match some branch, possibly the current one, possibly origin/master.

If naive builders are in use, such as Acceleo's, the reset may trigger a rebuild that makes the workspace dirty again.It may therefore be necessary to disable builds, synchronize, and overwrite the rebuilt files to lose the changes.

[edit] Create New Branch

You may create a new local branch in order to start development of some changes. This should almost always be created from an upstream branch, since this gives a simple direct relationship to the development stream. If you use another branch such as local master you create a branch of a branch and may encounter difficulties in synchronizing changes or exporting the branch to other repositories that may not be aware of all changes in your local master.

It is recommended to configure the pull stategy to rebase so that a Pull can be used to Fetch and Rebase Branch.

If you want to continue development on a pre-existing upstream branch you should Checkout an existing branch. This creates a local branch for which the remote branch is the upstream configuration, ensuring that Fetch and Push are useful.

If you want to continue development on a pre-existing local branch you should switch to it.

On no account check out a Remote Tracking branch directly. You may succeed in committing changes locally, but they will appear to get lost since they will not be synchronized with the remote branch that you have 'changed'.

[edit] Switch to Local Branch

You may switch to a local topic branch in order to resume work on that topic.

You may switch to a local release branch in order to perform a very simple development directly on the release.

You should switch to a local release branch in order to merge the rebased development from a topic branch into an upstream release.

[edit] Switch to Upstream Branch

You should not normally switch to an upstream branch or tag since this creates a detached HEAD. Any changes that you make are easily lost and difficult to retrieve.

You may switch to an upstream branch to review it, but don't forget that changes will get lost.

[edit] Review Workspace Changes

The changes awaiting commit may be displayed by Synchronize Workspace. This activates the Synchronize View in which comparisons can be reviewed.

[edit] Review Branch Changes

The changes between a current branch and another can be displayed by Synchronize. This activates the Synchronize View in which comparisons can be reviewed.

[edit] Commit to Branch

Changes are committed to the current branch. They can be committed directly from the Package Explorer view, but this offers limited opportunity for review.

It is recommended to Synchronize Workspace, so that all changes are displayed in the Synchronize View, allowing differences to be reviewed by double clicking files. The files to be committed may be selected and then committed.

Once all changes have been committed the Synchronize View should show no changes. Unfortunately the Synchronize View has limited understanding of .gitignore and so many spurious files suddenly show as needing a commit. It is currently necessary to return to the Package Explorer and resynchronize from there.

If naive builders are in use, such as Acceleo's, the commit may trigger a rebuild that then appears to show a need to commit further files. These files mark the workspace as dirty, preventing rebasing or switching. It may therefore be necessary to disable builds, resynchronize, and overwrite the rebuilt files to lose the changes.

[edit] Create Patch and Request Review

Patches are created by selecting a commit in the History View, so select the repository in the Git Repositories View and invoke Show in History. Then select the commit from which to create a patch.

TODO: Explain how to create a patch from A to B.

Attach the patch to the Bugzilla and set your email as the QA contact so that a Mylyn task searching for open bugs with an '@' in the QA contact will identify the patch as awaiting review.

[edit] Fetch and Rebase Branch

Before merging a change to upstream, you should minimize the opportunities for concurrency conflicts by Fetching from Upstream to update your workspace and Rebasing onto the upstream branch.

These two actions can be achieved by a Pull if you configure your branch pull strategy to Rebase.

In order to merge concurrent changes from for instance origin/master you Rebase onto the origin/master branch. This does not affect the origin/master branch.

Note that 'Rebase onto' refers to commit history rather than branch contents, so when branch A is rebased onto branch B, the commit history of branch A is changed to be the commit history of branch B with the residue of branch A onto of it. 'onto' does not suggest that the content of branch B is pasted onto branch A.

You cannot Rebase while your workspace has pending changes, so you must commit, or discard those before rebasing.

[edit] Merge Branch onto local master

Once your changes are ready for incorporation into the development stream, have been tested and your development stream is rebased, you may Merge the topic branch into the local master branch.

[edit] Push to Upstream

Once your changes have been tested in a local release branch such as master, you may push upstream to incorporate those changes in the corresponding upstream release branch such as origin/master.

A simple Push to Upstream pushes all local branches upstream, which may not be what you want, so you may want to do Team->Remote->Push... to control a Direct Push.

If concurrent changes have occurred, you must rebase to resolve the concurrency conflict.

[edit] Cherrypick Commits

When some commits developed for one stream, such as the master release stream, are also applicable to another stream, such as a maintenance stream, the commits may be reused by cherrypicking. After switching to the branch to be updated, Cherrypick the required commits.

It is recommended to cherrypick one at a time in forward order; multiple commits can lead to spurious conflicts.

If conflicts arise they must be Resolved.

[edit] Archive Old Branch

When the work of a topic branch has been resolved, the topic branch is renamed as archive/xxxxxx so that a hierarchical display of branches separates the active from resolved topic branches. GIT does not support direct operation on the upstream repository, so this rename is achieved by a (re-)creating the new archive/xxxxxx branch and deleting the old bug/xxxxxx branch.

You may archive many branches at once, provided you have an up-to-date local copy of each branch ready for pushing upstream again.

For each branch to archive, first Switch to Local topic Branch or Create New local Branch and Pull to update it. Then from the EGit repositories view, Push... and add a push specification to push bug/xxxxxx as archive/xxxxxx, and another to delete bug/xxxxxx.

This upstream change only partially propagates to other repositories, for which a Fetch from Upstream will show the new archive/xxxxxx, but will not prune the old bug/xxxxxx, so branches in the Remote Tracking list may be deleted to at least remove any matches for archived branches. It is safe to delete remote tracking branches speculatively, since they will reappear with a Fetch from Upstream.