This page collects the guidelines established in the git experiment.

This is a work in progress.

ASF GIT repositories are currently hosted at http://git-wip-us.apache.org/

For understanding the technical aspects of GIT and SVN please read SVNvsGIT. This will help you to grok the design decisions.

GIT at the ASF is currently an experiment. We have defined criteria under which this experiment should be considered successful.

Hosting

Canonical GIT repositories for Apache projects must be hosted on ASF hardware, under full control of the ASF infrastructure. This has quite a few reasons:

  1. Our Source Code Repositories are there for one reason: helping the community. This can best be supported by having one single canonical repository. Projects having multiple equitable repository clones tend to split the community.
  2. UserIDs outside of apache.org are not reliable! We can only guarantee a fully trusted authentication for servers we host ourselves!
  3. Authentication can later be extended to support login via ssh keys uploaded to http://id.apache.org (we need to drop this as infra ticket)

  4. Relying on external infrastructure for our own core business is frankly spoken pretty unwise. This would not only split the community but also would us make lose our independence. We would have no access to the underlying hardware, thus no way to handle threats if someone tries to taint our repositories.

Project Structure

  1. Each project has at least one GIT repository which contains the main project and is read/writable for all committers.
  2. Each project can optionally have a separated PMC-private GIT repository which conains confidential legal stuff like trademark contracts, creds for community accounts like twitter, etc
  3. Some projects might need additional GIT repositories containing project parts which have a completely separated lifecycle from the main project. This can be various build-tools (checkstyle-rules, project specific maven-plugins which are needed to build the project) or the project site. This is needed because a GIT branch and tag always affects the whole repository

GIT Hooks

We need to apply some hooks to the GIT repos to prevent the user from changing a few things.

  1. It must not be possible to change the history of a project or delete certain branches. Any sha1 in master or any productive branch must not be allowed to get changed!
  2. git-rebase, git-stash and stashing via git-merge --interactive is only allowed if the history of external contributions remains preserved.
  3. It must not be possible to delete release tags.

grobmeier: deleting tags is possible with SVN, for example when the RC1 tag has failed the vote. Why isn't it allowed with git?

Non-ASF repository collaboration

  1. Doing a test feature branch in private or in a forked github repository is perfectly fine. But committers should push to the canonical ASF repository early and often to prevent a fragmentation of the community development effort.
  2. Even if GIT supports the additional author information, the established policy that committers should apply their commits to the canonical repository themself remains intact.
  3. Committers pushing changes to the canonical repository must make sure that the committerIds and authorIds in the changes they submit are trustworthy (authenticated and iCLA on file).
  4. Pulling from some external (non apache.org hosted) repository must only happen if all the respective commits are done by a person which has an iCLA on file and if the diff of the pull-request is preserved on some ASF server. This can be done by extending JIRA to automatically download the diffs of a pull-request.The project shall not hesitate to animate people to sign our iCLA.
  5. Incorporating changes from other contributors (no iCLA on file) must only be handled via JIRA attached patches because of legal reasons (the 'grant inclusion under ALv2' flag in JIRA).
  6. The project documentation and project site shall mention the apache.org based GIT repo as the canonical source location.

Cutting Releases with GIT

The release plan from couchdb can be found here: http://wiki.apache.org/couchdb/Release_procedure

Apache Maven supports the usage of GIT with the maven-scm-providers-git since 2008.

Be aware that the branch created by a release with GIT always covers the whole repository.

Tagging during a VOTE

Please note that the only officially result of an ASF release is the source tarball! These zipped and signed sources are also the only thing a VOTE is upon. All other artifacts produced during a build are just nice to have goodies which are no official ASF products. This includes the TAG on any SCM hosted at the ASF or elsewhere.

Tagging policy in CouchDB

The following is true for CouchDB which decided to not use tagging at all while voting on a release: Do not tag a release until the vote has passed.

CouchDB does not issue release candidates in the same way that other projects do. When most users see a release candidate, they think of it as an officially sanctioned version of the software. If we tag our release artefacts (which may be prepared by anyone, at any time) as release candidates while we vote on them, we are sending the wrong message to anyone who finds that tag in the repository.

Even if we avoid calling them release candidates, all tags live in the same namespace, so we risk confusing our users if we tag the release artefacts we are voting on, as well as the release artefacts we have actually released. Deleting tags that correspond to failed votes will not help, because Git does not reliably propagate tag deletion to downstream repositories.

In answer to these concerns, vote emails must only reference the tree-ish used to prepare the release. When the vote passes must you tag the tree-ish. Preferably using the version number alone, as each Git repository corresponds to exactly one project. The resulting tags in Git form an accurate list of every official release, and every downstream repository will be eventually consistent.

Other possible tagging policies

The Apache Maven community suggests to create a tag during the release process (mvn release:prepare) and to just not push the tag immediately but only when the artifacts will be moved from staging to the main artifact repositories.

Usecases / Workflow comparison GIT/SVN

What are the current use cases with scm at the ASF? How does the known workflows with SVN compare to the new GIT workflows?

JIRA Integration

Many ASF projects use JIRA as an issue tracker (see JIRA at issues.apache.org). CouchDB is one such project which also happens to be the project selected for experimenting with Git at the ASF. Improving the community contribution workflow for the CouchDB project by demonstrating good integration JIRA and Git will help to ensure that the CouchDB Git experiment is deemed a success and ensure a low barrier to community contribution.

There is an INFRA ticket open to set up the Git plugin for JIRA (INFRA-4157).

The Cassandra project has some documentation and scripts to help managing patch series in JIRA and Git.

Unresolved Issues

When merging pull requests from GitHub, a merging practice which preserves authorship, minimizes history noise, and automatically closes the pull request issue would be ideal. Currently, no such flow is possible. Currently, either the contributor must close and re-issue a pull request in response to code review or the resulting merge has the "noise" of the post-review commits. Since we disallow merge commits as a policy, the pull request is not automatically closed. The committer should be able to close the pull request by stating so with the magic commit message commands (such as "fix #124"), but must take care if she wishes to make her commits in a way that preserves the original author information.

It's easy to conflate git and github, but the implications of each are significant. GitHub is a large community of coders who use a very slick interface to manage forks and branches across common projects, via issues, pull requests, and also wikis, websites and organisational structures and permissions. Do we want GitHub integration, or is an alternative like http://gitlabhq.com/ that can be directly hosted on ASF infrastructure, with an MIT license,going to meet the same ends?

Git_At_Apache_Guide (last edited 2012-11-03 21:11:27 by chello084112019176)