Current File : //usr/share/doc/xorg/reference/git-usage.html
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
<meta name="generator" content="AsciiDoc 10.2.0" />
<title>Git usage</title>
<link rel="stylesheet" href="../xsf.css" type="text/css" />
<script type="text/javascript" src="../asciidoc-xhtml11.js"></script>
<script type="text/javascript">
/*<![CDATA[*/
asciidoc.install(2);
/*]]>*/
</script>
</head>
<body class="article">
<div id="header">
<h1><a href="../index.html">XSF</a> / Git usage</h1>
<span id="author">Cyril Brulebois</span><br />
<span id="email"><code><<a href="mailto:kibi@debian.org">kibi@debian.org</a>></code></span><br />
<div id="toc">
<div id="toctitle">Table of Contents</div>
<noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
</div>
</div>
<div id="content">
<div id="preamble">
<div class="sectionbody">
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">The old documentation is still available on the wiki:
<a href="https://wiki.debian.org/XStrikeForce/git-usage">wiki.debian.org/XSF/git-usage</a>;
this documentation is just a draft for now.</td>
</tr></table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_getting_started">Getting started</h2>
<div class="sectionbody">
<div class="paragraph"><p>Upstream repositories are hosted on
<a href="https://cgit.freedesktop.org/">git.freedesktop.org</a></p></div>
<div class="paragraph"><p>Debian repositories are hosted on
<a href="https://salsa.debian.org/">salsa.debian.org</a> under the <code>xorg-team</code>
group. Each repository is about a single Debian source package.</p></div>
<div class="paragraph"><p>We have two types of repositories:</p></div>
<div class="ulist"><ul>
<li>
<p>
<strong>regular</strong> packages: 1 upstream repository → 1 Debian repository → 1
Debian source package (non-native).
</p>
</li>
<li>
<p>
<strong>bundle</strong> packages: multiple upstream repositories → 1 Debian
repository → 1 Debian source package (native).
</p>
</li>
</ul></div>
<div class="paragraph"><p>A local git repository can have several remotes. In the context of
Debian packaging, one usually starts by cloning the Debian repository,
so <code>origin</code> will likely point to <code>salsa.debian.org</code>. One can use
<code>upstream</code> to point to <code>anongit.freedesktop.org</code>. The following
documentation assumes this convention.</p></div>
<div class="paragraph"><p>The following bits in <code>~/.gitconfig</code> will make it possible to fetch
updates using <code>https</code> (anonymously), and to push updates
through <code>ssh</code> without having to fiddle with the remote’s URL (in other
words: using <code>https://salsa.debian.org</code> everywhere):</p></div>
<div class="listingblock">
<div class="content">
<pre><code>[url "ssh://git@salsa.debian.org"]
pushInsteadOf = "https://salsa.debian.org"</code></pre>
</div></div>
<div class="paragraph"><p>To get the repository from <code>salsa.debian.org</code> one can run <code>debcheckout
$package</code> (or <code>debcheckout $package $package.git</code>), which will use the
<code>Vcs-Git</code> fields in the APT cache to pick the appropriate git
location. To add the <code>upstream</code> remote (using the info stored in
<code>debian/watch</code>), one can use <code>xsf-remote-add-upstream</code> script from the
<a href="https://salsa.debian.org/xorg-team/debian/xsf-tools">xsf-tools</a>
repository.</p></div>
<div class="paragraph"><p><strong>TODO:</strong> There will be more information about how to deal with the
many repositories maintained by the X Strike Force in a later chapter.</p></div>
<div class="paragraph"><p>The usual workflow is to keep the target suite in <code>debian/changelog</code>
to <code>UNRELEASED</code> until the upload happens, the last commit before a
commit being only <code>dch -r</code>. To achieve that, and to avoid noise since
those packages are comaintained, it’s advised to set the following
variable in <code>~/.devscripts</code>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>DEBCHANGE_RELEASE_HEURISTIC=changelog</code></pre>
</div></div>
</div>
</div>
<div class="sect1">
<h2 id="_regular_packages">Regular packages</h2>
<div class="sectionbody">
<div class="paragraph"><p>For most packages (exceptions include <code>xorg-server</code>), development is
linear, and happens in a <code>master</code> branch. That <code>master</code> branch is
pushed in the Debian repository as <code>upstream-$suite</code>
(e.g. <code>upstream-unstable</code>), depending on the target suite. Usually,
<code>upstream-unstable</code> tracks <code>upstream/master</code>.</p></div>
<div class="paragraph"><p>The packaging is kept in <code>debian-$suite</code> branches, branched from
<code>upstream-$suite</code>. When cloning a Debian repository, the default
branch is <code>debian-unstable</code>.</p></div>
<div class="paragraph"><p>To create the initial packaging from the <code>upstream-unstable</code> branch,
just run <code>git checkout -b debian-unstable</code>, add packaging files
(<code>changelog</code>, <code>control</code>, <code>copyright</code>, <code>rules</code> etc. under <code>debian/</code>),
and that’s it.</p></div>
<div class="paragraph"><p>Here’s how to merge from upstream (<code>$foo</code> being a tag or
<code>upstream/master</code>):</p></div>
<div class="listingblock">
<div class="content">
<pre><code> git checkout upstream-unstable
git merge $foo
git log $foo > ChangeLog
dch -v $debianrevision
git commit -am 'Bump changelogs.'</code></pre>
</div></div>
<div class="paragraph"><p><code>$debianrevision</code> is usually <code>$foo</code> with <code>-1</code> appended (first upload),
and sometimes prepended with a epoch (for example <code>2:</code>). Passing
<code>$foo-1</code> is usually a good rule of thumb, since <code>dch</code> will complain if
the epoch is missing (given the specified version string wouldn’t be
newer than the current one).</p></div>
<div class="sect2">
<h3 id="_when_development_isn_t_linear">When development isn’t linear</h3>
<div class="paragraph"><p>For packages like <code>xorg-server</code> and <code>libx11</code>, there are stable
branches which receive updates for a while. Trying to switch from
<code>1.10.2</code> to <code>1.11.0</code> might trigger a lot of conflicts. But in the end
what matters is the changes between <code>upstream-$suite</code> and
<code>debian-$suite</code>. Here’s an example, supposing <code>upstream-unstable</code> and
<code>debian-unstable</code> are pointing to the “old” branches, and supposing
the new branch is <code>upstream/master</code>:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>git checkout -b debian-unstable-new upstream/master
git merge -s ours upstream-unstable
git merge debian-unstable
git branch -d debian-unstable
git branch -m debian-unstable</code></pre>
</div></div>
<div class="paragraph"><p>Subtitles:</p></div>
<div class="ulist"><ul>
<li>
<p>
Create a <code>debian-unstable-new</code> branch starting with the upstream
<code>master</code> branch, and switch to it.
</p>
</li>
<li>
<p>
“Merge” the old <code>upstream-unstable</code> branch, actually keeping only
the new upstream branch.
</p>
</li>
<li>
<p>
Merge the old packaging on top of it.
</p>
</li>
<li>
<p>
Remove the old branch (so that the name can be reused).
</p>
</li>
<li>
<p>
Rename the current <code>debian-unstable-new</code> branch into
<code>debian-unstable</code>.
</p>
</li>
</ul></div>
<div class="paragraph"><p>Since the tip of the new <code>debian-unstable</code> branch is a descendant of
the tip of the old <code>debian-unstable</code> one, it can be pushed normally.</p></div>
<div class="paragraph"><p>Since old <code>upstream-unstable</code> and new <code>upstream-unstable</code> diverged,
this branch has to be pushed with a <code>-f</code> to force the update (it’s not
a fast-forward).</p></div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_bundle_packages">Bundle packages</h2>
<div class="sectionbody">
<div class="paragraph"><p>One bundle package is a Debian native package, with just a (Debian)
tarball, instead of an upstream tarball plus a Debian diff.</p></div>
<div class="paragraph"><p>There is no upstream branches here, only <code>debian-$suite</code>.</p></div>
<div class="paragraph"><p>The repository contains a <code>debian/</code> directory for the packaging, and
one directory per upstream source. Merging a new upstream release
means updating the contents of the relevant directory with the
contents of the new upstream tarball. Fetching new tarballs is
automated through a specific target: <code>make -f debian/rules
get-tarballs</code></p></div>
<div class="paragraph"><p>To perform an update, first run <code>dch -i</code> to create a new changelog
entry if the previous commit was an upload (the new entry targets the
<code>UNRELEASED</code> suite, see “Foreword”).</p></div>
<div class="paragraph"><p>Assuming <code>get-tarballs</code> made <code>foo-bar.tar.gz</code> appear in the top-level
directory, here’s how to update (trailing slashes are not needed, just
there to clarify we’re working on directories):</p></div>
<div class="listingblock">
<div class="content">
<pre><code>git rm -r foo/
tar xf foo-bar.tar.gz
mv foo-bar/ foo/
git add foo/
dch "foo bar"
debcommit -a</code></pre>
</div></div>
<div class="paragraph"><p>Using the <code>xsf-remote-add-upstream</code> script will create several
<code>upstream-$foo</code> remotes, using info stored in <code>debian/watch*</code>. This
helps browsing the history of a given repository (rather than having
to look at a big fat diff with autogenerated files in the middle).</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_upgrade_checklist">Upgrade checklist</h2>
<div class="sectionbody">
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">Since it’s likely for a reader of this page to be on her way to update
a package, here’s a tiny upgrade checklist.</td>
</tr></table>
</div>
<div class="paragraph"><p>Basic checks include looking into what happened to those files since
the last packaging update:</p></div>
<div class="ulist"><ul>
<li>
<p>
<code>COPYING</code>: Update <code>debian/copyright</code> accordingly.
</p>
</li>
<li>
<p>
<code>configure.ac</code> (or <code>configure.in</code>): Update (build-)dependencies
accordingly.
</p>
</li>
</ul></div>
<div class="paragraph"><p>About xorg macros (they show up very often in the diff), they’re
shipped in the <code>xutils-dev</code> package, which contains a file to help map
macro versions and package versions:
<code>/usr/share/doc/xutils-dev/versions</code></p></div>
<div class="paragraph"><p>Some packages might have more specific instructions. That’s the case
for at least <code>xorg-server</code>. See its <code>debian/README.source</code>, below the
generic “how to use quilt” blurb.</p></div>
</div>
</div>
</div>
<div id="footnotes"><hr /></div>
<div id="footer">
<div id="footer-text">
Last updated
2020-10-09 09:18:55 UTC
</div>
</div>
</body>
</html>
Mini Shell