Daily development occurs in the '''master''' branch, but weekly integration builds are done out of a branch called '''integration'''. The builder takes care of tagging the build inputs and updating bundle qualifiers for those bundles that have changed. To contribute a repository to the build, do the following:

+

We do our latest release development in the '''master''' branch. Build contents are defined by the contents of the '''master''' branch of webtools.maps.git for latest development, and the '''maintenance''' branch for legacy development, such as '''R3_4_maintenance'''. Here is a rundown of how to update the contents of a build:

−

# Make sure you do a fetch on your repository

+

First, commit the code change locally and then push the change to git.eclipse.org.

−

# Ensure all desired changes for the build are in branch '''master'''

+

Then figure out what plugins and features were updated - you need to manually store this information.

−

# In the <b>Git Repositories</b> view, expand <b>Branches &gt; Local</b>, and select '''integration'''. Right click and select '''checkout'''. (Note: the very first time, you will need to first "create a branch" for '''integration'''.)

+

Tag the repository that was modified. (I had to do this by selecting a project in the Java perspective, brought up the context menu, and then selected Team->Advanced->Tag... and entered the appropriate Tag value and a comment.) Note that you tag the entire repository, and not just the plugins and features that changed. I saved the tag value that I entered (in Notepad) for later use.

−

# Select branch '''master''' and select '''merge'''

+

Push that tag to git.eclipse.org:

−

# Right-click on the repository and select '''Push to Upstream'''

+

−

# Remember to switch back to '''master''' to continue more new development.

+

−

To contribute to a build from the git command line, first ensure your local '''master''' stream contains the contents you want to contribute to the build. Then, do the following:

+

Go to the Git Repository Exploring view

+

Select the repository, bring up the context menu, and select Push... (not Push to Upstream, but Push...)

+

Hit Next>

+

Press the Add All Tags Spec button. Press Next> You should see the tag(s) you added since the last push show up with a new tag entry.

+

Press Finish

−

git pull

+

Made sure that you are using the right branch for the map files.

−

git checkout integration

+

(For WTP 3.4.1, the first time, I had to go to the Git Repository Exploring view, and do Switch to-> New Branch... and specify refs/head/R3_4_maintenance for the Source ref, and just type in R3_4_maintenance for the Branch name, and I specified rebase.)

−

git merge master

+

Update the tag value (using the value saved above) for the plugin(s) and feature(s) that were altered.

−

git push origin integration

+

Then commit and push the map files.

−

+

−

This will cause a fast-forward merge, so that both '''master''' and '''integration''' refer to the same commit. Past commits that were involved in builds will be identifiable by the build tag on that commit.

+

= Manual tagging =

= Manual tagging =

Revision as of 08:10, 20 August 2012

This page is a Web Tools Platform-specific version of [Platform-releng/Git_Workflows Platform-releng/Git_Workflows]

We'd like to capture some common CVS workflows used by the Web Tools Platform (WTP) and spell out the git/EGit equivalent. Please read this page even if you don't use EGit. It contains important instructions on how to setup your repository.

Please read some of Pro Git to get a feel for how git repositories work. Refer to the EGit/User Guide for more detailed instructions and pictures.

Configure the workspace

Open the Team > Git > Configuration preference page and on the User Settings tab add the user.name and the user.email property. If you don't want to share your e-mail you can also use your committer account ID. Note that you will not be able to push changes to the the repository if the latter property is not matching with your records at the Eclipse Foundation.

Set New text file line delimiter to Unix on the General > Workspace preference page.

Finish - Now just sit back while git copies the entire repo to your harddrive :-)

Configuring the repo

Unless you are working on topic branches, we work in a fairly linear history. Please set branch.branchname.rebase = true (see instructions below).

Make sure that you set core.autocrlf=false and on Windows core.filemode=false. If you use EGit to clone the repository then this is done automatically for you.

Once you've cloned a repository, you can go to the Preferences > Team > Git > Configuration page. Select your repository, select the branch you picked when you cloned the repository and click New Entry.... Append "rebase" to the text in the 'Key' field and enter "true" as value.

To automate the setting of "branch.branchname.rebase = true" if you use command line git, add "branch.autosetuprebase = always" to your global user settings. Unfortunately, this does not yet work properly in EGit, see Bug 345536 (fixed in EGit nightly build).

Importing the projects

We need to get the projects from the repo into our workspace:

right click on your newly cloned repo and select Import Projects

you want Import existing projects from the Working Directory

Next

Select the projects that you want to import from the repository

Finish

Now you can start working.

A note on deleting projects

Typically you will only want to have a subset of the projects from a given repository in your workspace. When you are no longer interested in a project, you can delete it from your workspace. However, NEVER select 'Delete project contents on disk' for a project in a git repository. If you do, Git will consider this an outgoing deletion to be committed to the remote branch. Later while working on a completely unrelated project you may accidentally commit this deletion (and you wouldn't be the first to do so).

Start working in HEAD

To start working in HEAD you must clone your repository and checkout a working copy. By default, cloning the repo checks out the master branch, which is the same as HEAD in CVS.

right click on one of your projects and choose Team>Switch To>New Branch

you need to pick a source ref.

HEAD == current checked out commit

refs/heads/master means your master branch.

refs/remotes/origin/R3_7_maintenance - the existing remote branch. If you pick this one and name your local branch the same, EGit will automatically create a tracked branch.

refs/tags/R3_7 is the tags to branch from

name the branch R3_7_maintenance

select the Rebase merge option

leave "Check out the new branch" selected.

This will create a new branch for you to work on. Once you've made your initial commits, you need #Commit_changes_to_the_main_repo. Pushing up to the repo will push any new branches you've created as well.

Contributing to a build

We do our latest release development in the master branch. Build contents are defined by the contents of the master branch of webtools.maps.git for latest development, and the maintenance branch for legacy development, such as R3_4_maintenance. Here is a rundown of how to update the contents of a build:

First, commit the code change locally and then push the change to git.eclipse.org.
Then figure out what plugins and features were updated - you need to manually store this information.
Tag the repository that was modified. (I had to do this by selecting a project in the Java perspective, brought up the context menu, and then selected Team->Advanced->Tag... and entered the appropriate Tag value and a comment.) Note that you tag the entire repository, and not just the plugins and features that changed. I saved the tag value that I entered (in Notepad) for later use.
Push that tag to git.eclipse.org:

Go to the Git Repository Exploring view
Select the repository, bring up the context menu, and select Push... (not Push to Upstream, but Push...)
Hit Next>
Press the Add All Tags Spec button. Press Next> You should see the tag(s) you added since the last push show up with a new tag entry.
Press Finish

Made sure that you are using the right branch for the map files.
(For WTP 3.4.1, the first time, I had to go to the Git Repository Exploring view, and do Switch to-> New Branch... and specify refs/head/R3_4_maintenance for the Source ref, and just type in R3_4_maintenance for the Branch name, and I specified rebase.)
Update the tag value (using the value saved above) for the plugin(s) and feature(s) that were altered.
Then commit and push the map files.

Manual tagging

Tagging for weekly integration builds is not needed, but sometimes you still need to tag. For example, tagging with a Rx_y tag when a release is done. To create a tag, use git tag mynewtag from the command line or the EGit Tag Dialog. Once a tag has been added, you must push the tag to the repository.

To push a specific tag, use git push origin mynewtag from the command line or use the following steps in EGit:

Team > Remote > Push...

Click Next to get to the Specifications Page

In the Source ref box, enter in refs/tags/mynewtag (content assist is available to quickly find a tag)

Click Add Spec

Click Next

Assuming the dry run is successful, click Finish

You can push all tags using git push --tags from the command line or pressing the Add All Tags Spec on the Specifications Page in EGit. However, this is risky as you will push all local tags and you will replace any tags that have been deleted from the remote repository.

The e4 Git page has some helpful scripts and additional information on tagging

Branches in our Platform Repos

We use a pre-receive hook in our repositories to enforce our branching/deleting policy.

committers can create, push anything, and delete their own topic branches on the remote repositories. Topic branches must have the form committerId/branchName. For example, pwebster/bug372119

committers can only push Fast Forward merges to the other branches, like origin/master or origin/R3_7_maintenance, or someone else's topic branch

committers cannot create or delete non-topic branches

committers can only delete tags with the same pattern as topic branches, committerId/tagName

Functionality can be re-enabled by setting certain config properties on the remote repository:

hooks.allownonffpush = true: Allow a non-FF push to any branch

hooks.allowdeletebranch = true: Allow any branch to be deleted

hooks.allowcreatenottopicbranch = true: Allow any branch to be created, like origin/R3_8_maintenance

hooks.allowdeletetag = true: Allow any tag to be deleted

Commit changes to the main repo

Committing a change to the main repo is a 2-step process in git. In git, a commit creates a commit with the changed files in your local clone repository. A push will put that commit in our main repo. Committing and pushing are distinct operations in git.

Dealing with line terminators

Git has various options for normalizing line terminators between Windows (which uses CR/LF), and other platforms that use only LF. After trying various approaches, the Eclipse project has settled on the following approach:

Set core.autocrlf=false. If you use EGit to clone the repository then this is done automatically for you.

In your workspaces set General > Workspace > 'New text file line delimiter' to 'Unix'.

In the current dev branches (do not do this in maintenance branches) set 'New text file line delimiter' to 'Unix' on the 'Resource' property page of your projects.

If you don't work with EGit then it is your responsibility to avoid committing wrong line delimiters to the repository.

If using Windows, set core.fileMode=false. Again, if you use EGit to clone the repository then this is done automatically for you.

Cross-referencing between bugzilla and git

Some committers like to attach patches to bugzilla for all changes, so they have a record of exactly what changes occurred to fix the bug. With git there is a better way:

Push the change to git.eclipse.org

Navigate to git.eclipse.org in your web browser

Find your repository, and click on the "Log" tab

Click on your commit, which should be near the top of the log at this point

You are now on a page that shows a graphical diff of call changes that occurred in that commit. Copy the URL of this commit page into a bugzilla comment.

Now if someone in the future wants to see what changes were made to fix the bug, they have a one click link to see all the changes.

Pruning corrupt repository branches

Sometimes a branch in your repository might get corrupted and you may see errors such as "Could not read an object while parsing commit ...." in Egit or "Branch .... does not point to a valid object". The following command comes handy in such scenarios:
git remote prune origin

(Always prefix a --dry-run to see what this command is going to do before you go ahead and execute it.)