rev 12345 - kde-extras
Mark Purcell
msp at alioth.debian.org
Mon Oct 6 00:31:54 UTC 2008
Author: msp
Date: 2008-10-06 00:31:54 +0000 (Mon, 06 Oct 2008)
New Revision: 12345
Modified:
kde-extras/README
Log:
Sync with pkg-voip README
Modified: kde-extras/README
===================================================================
--- kde-extras/README 2008-10-05 23:44:17 UTC (rev 12344)
+++ kde-extras/README 2008-10-06 00:31:54 UTC (rev 12345)
@@ -1,16 +1,15 @@
Debian kde-extras Team
-----------------------
+======================
1. Contacts
-----------
-
General help requests
<debian-kde at lists.debian.org> mailing list
- #debian-kde on irc
+ #debian-kde on irc.debian.org
Packaging queries
<debian-qt-kde at lists.debian.org> mailing list
- #debian-qt-kde on irc
+ #debian-qt-kde on irc.debian.org
Maintainers
<pkg-kde-extras at lists.alioth.debian.org> mailing list
@@ -18,30 +17,38 @@
2. Subversion repository
------------------------
-
You can browse it only at:
http://svn.debian.org/wsvn/pkg-kde/kde-extras/
To "checkout" the repository use these commands:
- $ svn co svn+ssh://${ALIOTH_USERNAME}@svn.debian.org/svn/pkg-kde/kde-extras
+* If you want a read-only copy, use:
-Authorized SSH keys are controlled at https://alioth.debian.org/account/
+ svn co svn://svn.alioth.debian.org/svn/pkg-kde/kde-extras
+* If you are a developer with an account at Alioth, you can also use:
+
+ svn co svn+ssh://${ALIOTH_USERNAME}@svn.debian.org/svn/pkg-kde/kde-extras
+
+Authorised SSH keys are controlled at https://alioth.debian.org/account/
+
The repository layout is:
+kde-extras/$package/{branches,tags,trunk}
+
- packagename/
- - trunk/
- - branches/
- - tags/
- - 0.7.2-1/
- - 0.7.2-2/
- - 0.7.2-2ubuntu1/
- - 0.7.2-2ubuntu2/
- - 0.7.2-2ubuntu3/
- - 0.8.0/
- ...
+ - trunk/
+ - branches/
+ - tags/
+ - 0.7.2-1/
+ - 0.7.2-2/
+ - 0.7.2-2ubuntu1/
+ - 0.7.2-2ubuntu2/
+ - 0.7.2-2ubuntu3/
+ - 0.8.0/
+- packagename2/
+...
If only one version of the package is available at the time, development must
be made at trunk/ dir, copying the dir to tags/'pkg-version' each time a new
@@ -50,24 +57,33 @@
When, at some point, the need to have two different versions at the same time
arises (for example, if we need a version to be in unstable and a different one
to be in experimental), experimental development will be made in trunk/ and
-if a new unstable package needs to be cooked, copying
-tag/'latest_version_in_sid' to tag/'latest_version_in_sid'+1 will make the
-trick.
+if a new unstable package needs to be cooked, copying tag/'latest_version_in_sid'
+to tag/'latest_version_in_sid'+1 will make the trick.
-The according Vcs-Svn and Vcs-Browser stanzas in debian/control are to
-have the following syntax:
+The according Vcs-Svn and Vcs-Browser stanzas in debian/control have the following
+syntax:
+
Vcs-Svn: svn://svn.debian.org/pkg-kde/kde-extras/$PACKAGE/trunk/
Vcs-Browser: http://svn.debian.org/wsvn/pkg-kde/kde-extras/$PACKAGE/?op=log
+
where of course $PACKAGE is the name of the SVN path (which should be identical
to the source name).
-Homepage: field should be added to all kde-extras packages (debian/control)
-to the Source part unless really useful to have Source and Package point
-to different URLs. The Homepage field is supported by dpkg-dev (>= 1.14.6).
+Homepage fields should be added to all kde-extras packages to the Source part
+unless really useful to have Source and Package point to different URLs.
+The Homepage field is supported by dpkg-dev (>= 1.14.6).
+If in doubt, sort the targets in debian/rules like this:
+ 1. headers, variable definitions
+ 2. includes (like dpatch, cdbs etc.)
+ 3. "build/build-arch/build-indep" targets including config.status and autotools/patch
+ 4. clean target (including unpatch)
+ 5. binnary target
+ 6. get-orig-source and print-version target
+ 7. .PHONY definitions
+
3. Using svn-buildpackage
--------------------------
-
Packages with an upstream tarball will require you to set the mergeWithUpstream
property first (from the package root) so that svn-buildpackage will look for
the .orig.tar.gz in the ../tarballs directory.
@@ -75,9 +91,16 @@
% svn propset mergeWithUpstream 1 debian
Please note that this only works for packages which have only the debian/
-directory committed. Consequently, you must use CDBS's simple-patchsys.mk or
-dpatch to modify the upstream sources.
+directory committed. Consequently, you must modify upstream sources indirectly
+using some patch system like CDBS's simple-patchsys.mk, CDBS + patchsys-quilt or
+dpatch.
+To download the *.orig.tar.gz to the ../tarballs directory, most of the
+kde-extras packages have a "get-orig-source" target in their debian/rules.
+Further, there is a "print-version" target showing the upstream version used for
+the current packaging. You can run the get-orig-source directly from trunk/ or
+tags/$version/.
+
After you have finished and committed your Debian patches via
% svn commit [PACKAGE]
@@ -85,13 +108,73 @@
as well as copying the orig.tar.gz to ../tarballs/ if necessary, you may build
your package with the following commands:
- % svn-buildpackage --svn-ignore-new -rfakeroot
+ % svn-buildpackage -rfakeroot
-Please, don't commit tarballs/ or build-area/ directories to SVN.
+You might want to add --svn-ignore-new to the flags if you do not want to
+commit before having finished your testbuild. Further, if you use debuild and
+edited /etc/devscripts.conf to use fakeroot by default, there is no need to add
+this to svn-buildpackage.
+svn-buildpackage provides svn-do, which you may find useful:
+ % /usr/share/svn-buildpackage/contrib/svn-do
+It executes svn-buildpackage --svn-export and enters that directory. After
+you change the tree as you like, exit the shell; your changes will be copied
+back to your working tree.
+Note, however, that it doesn't automatically "svn add" the new files that you
+may have created (e.g. debian/patches/foo); you'll have to do this manually.
+You may also want to edit the script and add --svn-ignore to the
+svn-buildpackage options.
+
+Don't commit tarballs/ or build-area/ directory contents to SVN! They would be
+wasting loads of bandwidth and there is no point.
+
+What you may find useful is setting these two:
+-------------------------------------------------
+$ cat >> ~/.devscripts <<EOF
+DEBCHANGE_RELEASE_HEURISTIC=changelog
+DEBCHANGE_MULTIMAINT_MERGE=yes
+DEBUILD_ROOTCMD=fakeroot
+DEBUILD_DPKG_BUILDPACKAGE_OPTS="-us -uc"
+DEBUILD_LINTIAN=yes
+DEBUILD_LINDA=yes
+DEFAULT_DEBRELEASE_DEBS_DIR=../build-area/
+EOF
+
+cat >> ~/.svn-buildpackage.conf <<EOF
+svn-builder=debuild
+svn-noautodch
+EOF
+
+-------------------------------------------------
+
+to make using "dch" just do the RightThing(TM).
+
+Common conventions for debian/changelog are:
+* "New upstream release" goes on top without having the Changed-By name
+ referring to it.
+* "NOT YET RELEASED" doesn't need to be added no more since "svn-noautodch" and
+ "DEBCHANGE_RELEASE_HEURISTIC=changelog"
+* distribution needs to be UNRELEASED for all pending patches and one of
+ unstable, proposed-updates, testing-proposed-updates etc. for uploaded
+ packages.
+* Grouping of Changed-By is largely appreciated. If there is only one editor,
+ the preamble with the name should be removed if it was added accidentally.
+ (use DEBCHANGE_MULTIMAINT_MERGE=yes will help a lot here)
+* Try to be verbose about what the change is and prefer "debcommit" to not have
+ different wordings for the same action. If SVN log and changelog match as
+ close as possible, it's easier to spot a change.
+* when releasing, use the text "Releasing $SOURCE ($VERSION) to $DIST." as SVN
+ commit message to make finding these updates more easy (and eventually allow
+ for a hold-back through IRC).
+
+To have a broader understanding of what problems are already assigned, use the
+"tagpending" whenever you think your fix is ready to solve the problem. For all
+the other manipulation like bug forwarding etc. using the "bts" commandline tool
+may come in handy.
+
+
4. Tarballs and Build-area directories
------------------------------------
-
During pkg development before uploaded to debian the tarballs can be found at:
http://pkg-kde.alioth.debian.org/kde-extra/orig.tar.gz/
@@ -100,13 +183,20 @@
running svn-buildpackage. Usually this means placing tarballs/ and build-area/ dirs
in 'pkgname'/ dir, at the same level as trunk/
-If you want to compile inside one version in tags/ dir, you'll need to place those
-dirs inside that dir. Of course the easiest and cleanest way of doing it is
-by making a symlink of those dirs inside tags/ dir.
+For the existing projects these are preset as symlinks to a central hierarchy
+under the SVN root. This is to facilitate the building of subsequent
+packages when having the full tree checked out.
+ If you want to compile inside one version in tags/ dir, you'll need to place those
+dirs inside that dir. Also for most of the tags dirs there should be ready to
+use symlinks.
+
+With DEFAULT_DEBRELEASE_DEBS_DIR pointing to ../build-area you can just use the
+"debrelease" command from the trunk/ directory after running svn-buildpackage
+--svn-tag.
+
5. Using svn-inject
-------------------
-
To inject a new package into the Debian KDE Extras svn archive you should use svn-inject(1)
as follows:
@@ -117,48 +207,100 @@
package.orig.tar.gz to your tarballs directory. The -o option is important as
this ensures that we 'Only keep modified files under SVN control'
-6. Versioning
+6. Patch management systems
+---------------------------
+Since all of our packages use mergeWithUpstream (we only keep debian/ in the
+repository) a patch management system should be used to make changes to
+upstream files.
+Most of the packages use dpatch, except a few that use quilt. The latter is
+recommended for big patch-sets, even though it could be used for small ones, if
+the maintainer prefers it.
+
+6.1. dpatch
+~~~~~~~~~~~
+Using dpatch is as easy as putting
+-------------------------------------------------
+ include /usr/share/dpatch/dpatch.make
+-------------------------------------------------
+to your debian/rules. This creates three new targets, "patch" and "unpatch"
+which are phony and patch-stamp that's not phony which can be used as depends
+upon on configure and clean respectively. For clean you'll need to make sure
+unpatch is run after the regular cleanup or rerun builds will fail in clean.
+
+6.2. quilt
+~~~~~~~~~~
+Similarly, using quilt is as easy as putting
+-------------------------------------------------
+ include /usr/share/quilt/quilt.make
+-------------------------------------------------
+to your debian/rules. This creates three new targets, "patch" and "unpatch"
+which are phony and patch-stamp that's not phony which can be used as depends
+upon on configure and clean respectively. For clean you'll need to make sure
+unpatch is run after the regular cleanup or rerun builds will fail in clean.
+
+
+It is recommended to use these settings so that you can move around on your
+series with quilt:
+-------------------------------------------------
+cat >> ~/.quiltrc <<EOF
+QUILT_PATCHES="debian/patches"
+
+QUILT_PATCH_OPTS="--unified-reject-files"
+QUILT_REFRESH_ARGS="-p ab --no-timestamps --no-index"
+QUILT_DIFF_OPTS="--show-c-function"
+QUILT_DIFF_ARGS="-p ab --no-timestamps --no-index --color=auto"
+EOF
+
+-------------------------------------------------
+Consult quilt(1) for more information of what these options do.
+
+7. Versioning
-------------
-
-As the autobuilder and fellow developers will need to differentiate between
+As the auto-builder and fellow developers will need to differentiate between
versions that are uploaded into debian already and those which will be at a
later point, do use the UNRELEASED distribution until the time you actually do
upload to incoming. Whoever is not a DD himself should let the sponsor do that
final step if that sponsor has SVN commit rights to the kde-extras archive.
-The autobuilder packs can be found at http://kde-extras.buildserver.net/.
-The logs can be found at http://status.buildserver.net/.
-
-As the archive runs britney, it may well be that a built and installed package
-is not appearing to the archive until its reverse depends are (re)built too. In
-case of questions, feel free to mail kilian at debian.org.
-
-7. Automatic Backport hooks
----------------------------
-
-The checkout script for putting together the sources can run a backports hook
-for certain dists (like Debian sarge) which need certain adjustments to the
-source like altered Build-Depends. This hook is a plain shell script (or
-makefile like debian/rules) which needs to be put in the debian/backports
-directory and made executable by means of the svn properties set. The codenames
-for the current dists are: sid, etch, sarge, edgy and dapper. For an example
-see asterisk-addons/trunk/debian/backports/sarge which may be more illustrating
-what to do.
-
-8. Commit Policy
+9. Commit Policy
----------------
-
In general, people with commit access are allowed to commit everywhere and
should make sure that they are in the Uploaders field and make sure to also
note the changes in the changelog. Major changes should be discussed with
-existing people in Uploaders fiellld.
+existing people in Uploaders Field.
If some packages should be restricted, the people in uploaders field can add a
file called kde-extras/$package/commit-policy where commit policies can be
described in free form text, and can also include policies for uploading the
package.
+10. Building from debcheckout
+----------------------------
+This section is for someone who does not normally build kde-extras
+packages and wants to build the latest version of a certain package
+without all the extra setup mentioned above.
+
+Required packages (beyond the build requirements of the package)
+* svn-buildpackage (and subversion itself, of course)
+* devscripts
+
+Here is an example build of the package libkexiv2:
+
+ # apt-get build-dep libkexiv2
+
+ $ debcheckout libkexiv2
+ $ cd libkexiv2
+ $ ./debian/rules get-orig-source
+ $ svn-buildpackage -uc -us
+
+If all worked well, svn-buildpackage will print out the locations of the
+binary packages it has generated. They will be built in the directory
+../build-area/ .
+
+
-(snip)-
In case any of the above is unclear to you or seems outdated, please drop us a
note to the maintainers list.
+
+ pkg-kde-extras at lists.alioth.debian.org
More information about the pkg-kde-commits
mailing list