www-infrastructure-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jukka Zitting <jukka.zitt...@gmail.com>
Subject Moving Git instructions to www.apache.org
Date Sun, 03 May 2009 11:20:11 GMT
Hi,

I'm about to start migrating some of the Git instructions we currently
have on the wiki to a more "official" location on the www.apache.org
web site.

See below for my first shot at the content I'm about to publish at
http://www.apache.org/dev/git.html. As a new part I'm including a
section with a proposed workflow for contributors that use Git. The
instructions for the committer workflow IMHO still need some work so
for now I was thinking of leaving them on the wiki.

Once I have this page published, I'll be posting an entry on the Infra
blog about the Git mirrors we have.

BR,

Jukka Zitting


<?xml version="1.0"?>
<!--
  Licensed to the Apache Software Foundation (ASF) under one
  or more contributor license agreements.  See the NOTICE file
  distributed with this work for additional information
  regarding copyright ownership.  The ASF licenses this file
  to you under the Apache License, Version 2.0 (the
  "License"); you may not use this file except in compliance
  with the License.  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing,
  software distributed under the License is distributed on an
  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  KIND, either express or implied.  See the License for the
  specific language governing permissions and limitations
  under the License.
-->
<document>
  <properties>
    <title>Git access to Apache codebases</title>
  </properties>
  <body>
    <section>
      <title>Git access to Apache codebases</title>
      <p>
        The Apache Software Foundation uses
        <a href="http://subversion.tigris.org/">Subversion</a> as the main
        <a href="version-control.html">version control</a> infrastructure,
        but we also provide some level of support to users of the
        <a href="http://git-scm.com/">Git</a> version control system.
        This page describes how you can use Git with Apache codebases.
      </p>

      <toc/>

      <section id="git-mirrors">
        <title>Git mirrors</title>
        <p>
          We maintain read-only Git mirrors of many Apache codebases at
          <a href="http://git.apache.org/">http://git.apache.org/</a>.
          These mirrors contain the full version histories (including all
          branches and tags) of the mirrored codebases and are updated in
          near real time based on the latest svn commits.
        </p>
        <p>
          The mirrors can be cloned or pulled from using got the Git and
          HTTP protocols. See the mirror page for the available clone URLs.
        </p>
        <p>
          Please file an
          <a href="https://issues.apache.org/jira/browse/INFRA">INFRA</a>
          issue (component: Git) to request a new codebase to be mirrored
          or to change the settings of an existing mirror. When requesting
          a new mirror, please include the following information:
        </p>
        <ul>
          <li>
            Name of the codebase, for example "Apache Tika"
          </li>
          <li>
            Name of the requested Git mirror, for example "tika.git"
          </li>
          <li>
            Subversion path of the codebase, for example "/lucene/tika/"
          </li>
          <li>
            Subversion layout, in case it is different from the standard
            "trunk, branches, tags" structure.
          </li>
        </ul>
      </section>

      <section id="workflow">
        <title>Proposed workflow</title>
        <p>
          This is a proposed workflow for using Git with an Apache codebase.
          This workflow is mainly targeted to contributors who don't already
          have commit access to a project.
        </p>
        <p>
          Once you have cloned or pulled the latest changes to your local
          Git repository of an Apache codebase, you can start working on it.
          Whenever you make some changes to the codebase, it's good to have
          a related issue filed in the issue tracker of the project and to
          use a similarly named branch in your Git repository. For example,
          to create a branch for an issue with the key TIKA-123.
        </p>
        <pre>git branch TIKA-123 origin/trunk</pre>
        <p>
          With per-issue branches you can easily switch back and forth between
          different issues without worrying about unwanted side-effects from
          unfinished changes to other issues. Whenever you want to work on
          the TIKA-123 example issue, simply checkout that branch and start
          making your changes.
        </p>
        <pre>git checkout TIKA-123</pre>
        <p>
          It's a good idea to commit your changes whenever you have finished
          one logical part of the issue. For example when refactoring, make
          a new commit for each refactoring step you take.
        </p>
        <pre>git commit</pre>
        <p>
          Once you're ready to share your changes with the rest of the project
          team, you can use the git format-patch command to produce a nice
          set of patches to attach to the relevant issue.
        </p>
        <pre>git format-patch origin/trunk</pre>
        <p>
          The sooner you share your work the better. You can repeat the
          steps of this workflow as often as you like, producing more patches
          to be attached to the issue tracker. Once some of your patches are
          accepted and committed to svn, you can rebase your work against the
          latest trunk. Alternatively, if you're asked to make some changes,
          you can go back to the original Git commit and modify it until the
          project team accepts your changes.
        </p>
      </section>

      <section id="improvements">
        <title>Ongoing improvements</title>
        <p>
          Improvements to Git support at Apache are being discussed on the
          <a href="infra-mail.html">infrastructure-dev@ mailing list</a>.
          This list is open to everyone and is
          <a href="http://mail-archives.apache.org/mod_mbox/www-infrastructure-dev/"
            >publicly archived</a>. You can subscribe this mailing list by
          sending a message to
          <a href="mailto:infrastructure-dev-subscribe@apache.org?subject=subscribe"
            >infrastructure-dev-subscribe@apache.org</a>.
        </p>
      </section>

    </section>
  </body>
</document>

Mime
View raw message