Guidelines for maintaining Octave-related Debian packages ========================================================= :Authors: Rafael Laboissiere and the Debian Octave Group :Contact: pkg-octave-devel@lists.alioth.debian.org .. contents:: 1. Coordination --------------- The development of Octave-related packages in Debian is done as a collaborative work by the Debian Octave Group (DOG) at alioth.debian.org. Any maintainer/developer, either a DD or not, interested in Octave related packages is encouraged to join the pkg-octave project at Alioth. Issues are discussed in the pkg-octave-devel mailing list. For more information about subscription and for looking at the archives, please visit http://lists.alioth.debian.org/mailman/listinfo/pkg-octave-devel Besides the common development of the Octave-related packages, the DOG will eventually improve the common build infrastructure, which will result in a better integration of the packages in the Debian distribution. 2. Building and uploading packages ---------------------------------- The first thing to do when contributing a new package is to set the maintainer to Debian Octave Group in debian/control. The debian/changelog entries should look like this:: octave-cool (1.2.3-4) unstable; urgency=low [ Dirk Eddelbuettel ] * Rebuilt with cool stuff [ Rafael Laboissiere ] * Cool tweaks -- Rafael Laboissiere Mon, 15 Oct 2012 08:30:00 -0400 Notice that the name of the official Debian maintainer who did the package upload for that specific version should appear in the trailer line. This is the common practice in Debian, being the format adopted in core packages like libc6 and xorg-x11. If you are a Debian developer, put your name in the Uploaders field of debian/control. By doing this, your uploads will not be considered as NMUs (non-maintainer uploads). URLs of the SVN repository can be added to the Source section of the debian/control file, which will appear in the Package Tracking System (http://packages.qa.debian.org). They should read like this:: Vcs-Svn: svn://svn.debian.org/svn/pkg-octave// Vcs-Browser: http://svn.debian.org/wsvn/pkg-octave// Once a developer thinks that a given package in the SVN repository is ready for upload, a message should be dropped in the pkg-octave-devel mailing list containing a request for upload (RFU) and using the format "[RFU] " in the Subject line. If there are no objections within two business days, at least, the upload can be done by one of the official Debian developers of the DOG. 3. SVN repository ----------------- The packages are under Subversion control at svn.debian.org. For more information on Subversion, please look at the web site http://subversion.tigris.org. The Subversion book is also a valuable resource and is available at http://svnbook.red-bean.com/. Automatic SVN activity is sent to the pkg-octave-commit mailing list. For more information, please visit http://lists.alioth.debian.org/mailman/listinfo/pkg-octave-commit Bugs marked as *closed* in debian/changelog will be tagged *pending* automatically when you commit your changes into SVN. The repository is organized in a svn-buildpackage-friendly way, as follows:: svn://svn.debian.org/svn/pkg-octave/ octave/ trunk/ debian/ octave2.1/ tags/ 2.1.64-3/ 2.1.64-4/ [...] branches/ [...] octave-forge/ trunk/ debian/ tags/ 2004.11.16-3/ 2004.11.16-4/ [...] branches/ [...] [...] Notice that only the debian files are put under Subversion control. No upstream files, please. As regards tag conventions, use the following path:: svn://svn.debian.org/svn/pkg-octave//tags// Only create a tag in /tags/ after the Debian version is actually released. This avoids having to issue extra svn copy commands if the tag is created too early. Comparison between two released Debian versions of a given package can then be done with a command like the following:: svn diff \ svn+ssh://svn.debian.org/svn/pkg-octave/octave-cool/tags/1.2.3-3 \ svn+ssh://svn.debian.org/svn/pkg-octave/octave-cool/tags/1.2.3-4 To put a new package under Subversion control, use the `svn-import-pkg`_ script or follow this cookbook: * Create the directory for the new package, as well as the subdirectories trunk and tags:: svn mkdir svn+ssh://svn.debian.org/svn/pkg-octave/octave-cool \ svn+ssh://svn.debian.org/svn/pkg-octave/octave-cool/trunk \ svn+ssh://svn.debian.org/svn/pkg-octave/octave-cool/trunk/debian \ svn+ssh://svn.debian.org/svn/pkg-octave/octave-cool/tags \ --message 'Created directory structure for octave-cool package' :note: This only works if your user name in the system you are working is the same as your user name in Alioth. If this is not the case, you will need to set the SVN_SSH environment variable, like this:: export SVN_SSH="ssh -l my-alioth-username" Otherwise, you can add your Alioth user name directly in the URL:: svn co svn+ssh://my-alioth-username@svn.debian.org/svn/pkg-octave Yet another solution, probably the best one, is adding to your personal configuration file ~/.ssh/config something like:: Host svn.debian.org User my-alioth-username * Get the latest released version of the package:: apt-get source octave-cool * Import the Debian-related files into the repository:: svn import octave-cool-1.2.3/debian \ svn+ssh://svn.debian.org/svn/pkg-octave/octave-cool/trunk/debian \ --message 'Initial import of package octave-cool' * Tag its current version:: svn copy svn+ssh://svn.debian.org/svn/pkg-octave/octave-cool/trunk \ svn+ssh://svn.debian.org/svn/pkg-octave/octave-cool/tags/1.2.3-4 \ --message 'Debian release 1.2.3-4' \ :note: At this point you will have a debian/ directory containing .svn/ directories. In order to avoid this directories to sneaking into the .diff.gz file (and making Lintian unhappy), use the -i option to debuild or dpkg-buildpackage. Developers who are not members of the DOG can access the SVN repository anonymously. * The whole tree:: svn co svn://anonymous@svn.debian.org/svn/pkg-octave * The sources of a specific package:: svn co svn://anonymous@svn.debian.org/svn/pkg-octave//trunk/ When committing changes that do not result in a Debian release, keep debian/changelog in a clearly broken state, such that the other developers will know that the version is not yet released. The preferable way of doing this is by setting the distribution to "UNRELEASED", like this:: octave-cool (1.2.3-4) UNRELEASED; urgency=low [ Joe Developer ] * First import -- Joe Developer Mon, 15 Oct 2012 08:30:00 -0400 Notice that the trailer line should be kept in the changelog entry. This has the following advantages: first, it keeps the package in a buildable state from a SVN checkout. In addition, the trailer line shows the name of the developer who effectively prepared that version of the package and which will appear in the "Changed-By:" field of the \*.changes file. The change from "UNRELEASED" to "unstable" (or any other valid distribution) should be done by the developer who does the actual upload. 4. Centralized installation paths and octave2.1 dependency ---------------------------------------------------------- Starting with the release 2.1.65-1, some common build infrastructure has been added to the octave2.1-headers package. The goal is to have more uniform octave-releated and to avoid incompatibility problems at every new release of Octave, even when the API counter is not incremented. These are the instructions for the developers: 1) Build-Depends on octave2.1-headers (>= 2.1.73-10) or octave2.9-headers (>= 2.9.7-2). This is necessary to get access to files defs.make and octave-depends (attached below). 2) At the top of debian/rules put the following:: include /usr/share/octave/debian/defs.make This defines the Makefile variables MDIR and OCTDIR containing the installation paths for .m scripts and .oct loadable modules. Use these variables to install files in the package. For instance, the following example:: ########################################## include /usr/share/octave/debian/defs.make all: @echo MDIR: $(MDIR) @echo OCTDIR: $(OCTDIR) ########################################## would give something like:: $ make MDIR: /usr/share/octave/site/m OCTDIR: /usr/lib/octave/site/oct/api-v13/i386-pc-linux-gnu 3) In the install rule of debian/rules, call 'octave-depends' (typically near dh_shlibdeps). This is a debhelper-like program that calculates the right Octave dependency. If you have in debian/control:: Depends: ${octave:Depends} then octave-depends would give something like:: Depends: octave2.1 (>= 2.1.65) For setting the dependency on specific branches of octave, use the variables ${octave-2-1:Depends} or ${octave-2-9:depends}, associated with octave2.1-depends and octave2.9-depends, respectively. For an example of using both scripts, see the octave-epstk package. Notice that the dependency above will keep compatibility with later versions of octave2.1. This is also insured by the fact that the $(OCTDIR) path does not contain a version number, only the API number. Only in the event a newer version of octave2.1 bumps the API number, then we will have to rebuild all the packages containing .oct files. 5. Web area at alioth.debian.org -------------------------------- The web area for the Debian Octave group is located at /org/alioth.debian.org/chroot/home/groups/pkg-octave on the alioth.debian.org server. The web site for the DOG is currently automatically generated from the sources maintained in the SVN repository at:: svn://svn.debian.org/svn/pkg-octave/www/ Maintainers manipulating the files in the web area by hand should be carefull to keep access rights to the pkg-octave group. Author ------ Rafael Laboissiere in the behalf of the Debian Octave Group | $Id$ | `(view source)`_ `(view history)`_ `(PDF version)`_ .. _(view source): DOG-Guidelines.txt .. _(view history): http://svn.debian.org/wsvn/pkg-octave/www/DOG-Guidelines.txt?op=log&rev=0&sc=0&isdir=0 .. _(PDF version): DOG-Guidelines.pdf .. _svn-import-pkg: http://svn.debian.org/wsvn/pkg-octave/utils/svn-import-pkg?op=file&rev=0&sc=0 .. Local variables: .. mode: rst .. End: