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

From Eclipsepedia

< MDT‎ | OCL
Jump to: navigation, search
(Major Change)
Line 37: Line 37:
  
 
== Workflows ==
 
== 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.
 +
 +
* Optionally [[#Discard Old Work | Discard Old Work]] to facilitate doing something new
 +
* [[#Fetch from Upstream | Fetch from Upstream]] to update your local repository
 +
* [[#Switch to Local Branch| Switch to local/'''master''']]
 +
* [[#Pull from Upstream | Pull from Upstream]] to synchronize with development stream
 +
* Develop and test changes
 +
* Optionally [[#Review Changes | Review Changes]] prior to commit
 +
* [[#Commit to Branch | Commit to local/'''master''']]
 +
* [[#Rebase Branch | Rebase local/'''master''' onto '''origin/master''']]
 +
* [[#Push to Upstream | Push to Upstream]] to commit local/'''master''' to '''origin/master''' release stream
  
 
===Major Change===
 
===Major Change===
Line 62: Line 76:
 
* [[#Archive Old Branch | Archive Old Branch]] to prune the EGit displays
 
* [[#Archive Old Branch | Archive Old Branch]] to prune the EGit displays
  
===Minor Change===
+
===Maintenance 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.
+
Some changes to the master release stream may also be applied to a maintenance stream.
  
* Optionally [[#Discard Old Work | Discard Old Work]] to facilitate doing something new
+
* Perform [[#Major Change | Major Change]] to the master release stream
* [[#Fetch from Upstream | Fetch from Upstream]] to update your local repository
+
* [[#Create New Branch | Create local maintenance Branch]] or [[#Switch to Local Branch | Switch to local maintenance Branch]]
* [[#Switch to Local Master| Switch to local/'''master''']]
+
* [[#Cherrypick Commits | Cherrypick Commits]] to update the maintenance branch
* [[#Pull from Upstream | Pull from Upstream]] to synchronize with development stream
+
* Redevelop and test changes
* Develop and test changes
+
 
* Optionally [[#Review Changes | Review Changes]] prior to commit
 
* Optionally [[#Review Changes | Review Changes]] prior to commit
* [[#Commit to Branch | Commit to local/'''master''']]
+
* [[#Commit to Branch | Commit to local maintenance Branch]]
* [[#Merge Branch onto origin/master | Merge local/'''master''' onto '''origin/master''']] to commit to the development stream
+
* [[#Push to Upstream | Push to Upstream]] to update upstream maintenance release stream
  
 
== Use Cases ==
 
== Use Cases ==

Revision as of 13:23, 30 July 2011

The capabilities of EGit are described at 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

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 may not be changed/interleaved
  • pulling from upstream is easy

therefore:

  1. NEVER rebase an upstream release branch onto anything
  2. ALWAYS rebase onto an upstream release branch before merging into it
  3. ALWAYS create local development branches from an upstream branch

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.

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.

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 [|epositores 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.

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.

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 branch whose name starts with bug/nnnnnn where nnnnnn is the Bugzilla number. A short description may follow.

Maintenance Change

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

Use Cases

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. 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.

TODO - instruction for pushing key to eclipse.org.

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.

Fetch from Upstream

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

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.

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.

If you want to continue development on a pre-existing 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.

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

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 detached HEAD. Any changes that you make are easily lost and difficult to retrieve.

Review Changes

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.

Create Patch

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.

Request Review

Synchronize Branch with origin/master

With the Branch checked out, you may Rebase Branch onto origin/master or you may Merge origin/master onto Branch to synchronize with concurrent development.

You're right; you should remain on the bug branch after a rebase according to the man page. I usually work the other way around and I couldn't say if one is better than the other. What I like about a "git merge master" is that it doesn't need to re-write my commits which later simply merge unchanged into master whereas a "rebase" produces a chain of new commits. "rebase" may be more appropriate in case some of the commits already got cherry-picked into master.
See above, both are valid with subtle differences as to which commits remain in place and which ones are re-written / cherry-picked. It leads to a slightly different commit tree eventually, but the snapshot produced by both should be equivalent.

Rebase Branch onto origin/master

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.

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

Merge Branch onto local/master

Once your changes are ready for incorporation into the development stream, you first update your local development stream to incorporate these changes, test them and then push the updated development stream to the origin/master.

  • Switch to the local/master branch.
  • Fetch from Upstream to ensure it is up to date
  • Merge your branch into the local/master
  • Rebase local/master onto origin/master to sequentialize the concurrency

Push to Upstream

Once your changes have been tested in a local/master branch, a simple Push to Upstream may incorporate those changes in the origin/master.

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

Merge Branch onto origin/master

Merge Branch onto Another Branch

Archive Old Branch