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

Revision as of 11:25, 29 July 2011

The Eclipse OCL code is maintained in a GIT repository which is used by 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 at EGit/User Guide. The documentation here is complementary, it describes how the committers use EGit to satisfy typical use cases.

Complete Use Cases

Develop a Non-trivial 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.

A Bugzilla describes the intended change and supports communication regarding the progress of the 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.

• Optionally Discard Old Work to facilitate doing something new
• Create New Branch or Switch to Local Branch or Switch to Remote Branch
• Develop and test changes
• Optionally Review Changes prior to commit
• Commit to Branch
• Optionally Push to Upstream to create a backup at Eclipse or to publish to other committers
• Optionally Create Patch to attach to Bugzilla for review
• Optionally Request Review
• Synchronize Branch with origin/master to align with concurrent development
• Optionally Review Changes prior to merge
• Fetch to local/master to resynchronize local version of master development stream
• Merge Branch onto local/master to create updated local stream
• Rerun tests
• Push to Upstream to commit local to origin master development stream
• Optionally Merge Branch onto Another Branch such as a maintenance branch
• Archive Old Branch to prune the EGit displays

Develop a Trivial 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.

• Discard Old Work to facilitate doing something new
• Switch to local/master
• Pull from Upstream to synchronize with development stream
• Develop and test changes
• Optionally Review Changes prior to commit
• Commit to local/master
• Merge local/master onto origin/master to commit to the development stream

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

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

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 to match some branch, possibly the current one, possibly origin/master, the synchronizing the workspace, and overwriting to lose all changes.

Switch to Local Branch

Switch to Remote Branch

If the remote branch is relatively new you may need to Fetch from Upstream to update your list of Remote Tracking branches.

Then select any Git project and Switch to Remote Branch. The decoration on all projects should change to show that the selected branch is in use.

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

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 origin/master

Merge Branch onto Another Branch

Archive Old Branch