data/pkgmaint_guide.txt

   1 =============================================================================
   2             THE QUICK AND DIRTY ON HOW TO BE A PACKAGE MAINTAINER
   3 =============================================================================
   4                                              questions to jvinet@zeroflux.org
   5
   6 1. Follow Package Guidelines
   7
   8    Package guidelines can be found in the Arch Linux documentation.
   9    Please follow them closely.
  10
  11 2. How To Use CVS
  12
  13    The example commands below assume the module 'extra'.
  14
  15    2.1  Make sure your CVSROOT environment variable is set properly.  If the
  16         CVS repository is on the same box:
  17           # export CVSROOT=/home/cvs-extra
  18
  19         If you want to access the repository from the different box via SSH:
  20           # export CVS_RSH=ssh
  21           # export CVSROOT=:ext:user@cvs.archlinux.org:/home/cvs-extra
  22
  23    2.2  Checkout the repository.  This will download the entire repository to
  24         your local machine:
  25           # cvs co extra
  26
  27    2.3  Updating the repository.  This syncs your local repository with the
  28         master.  You should do this often, especially if other people could be
  29         working on the same repository.
  30           # cd extra
  31           # cvs -q update -d
  32
  33    2.4  Adding files/directories to the repository.  When you want to add a new
  34         package you should create a directory under the respective category and
  35         place the new PKGBUILD in it.  For example, to add fvwm to the repo:
  36           # cd extra/x11
  37           # mkdir fvwm
  38           # cd fvwm
  39           # cp /var/abs/PKGBUILD.proto ./PKGBUILD
  40           <edit, test, build, etc>
  41           # cd ..
  42           # cvs add fvwm
  43           # cvs add fvwm/PKGBUILD
  44
  45    2.5  Committing changes. Files are not written to the master repository until
  46         you commit.  Never forget to commit!
  47           # cd extra
  48           # cvs commit
  49
  50         This will find all modified files, then throw you into vi where you can
  51         add a log message describing your changes.  Save and exit from vi when
  52         you're done and cvs will update the files in the master repository.
  53
  54    2.6  Removing files.  If you need to remove a file (eg, an old patch that
  55         isn't needed anymore), you can do the following:
  56           # cd extra/x11/fvwm
  57           # rm old.patch
  58           # cvs remove old.patch
  59           # cvs commit -m "removed old.patch" old.patch
  60         also remove the CURRENT/STABLE tags from the file so it does not appear
  61         in ABS any more:
  62           # cvs tag -d CURRENT old.patch
  63
  64         Don't forget to commit afterwards!  Remember that no changes are made
  65         to the master until you commit.
  66
  67    2.7  Removing directories cannot be done easily.  If you really need to
  68         remove a directory, email the sysadmin (Judd) and I'll help you out.
  69
  70    2.8  Tagging files.  Every file in CVS has tags associated with it, which
  71         allows us to select certain versions of scripts.  The db generation
  72         scripts will only look at files that are tagged as CURRENT, so you need
  73         to tag all files after you commit them:
  74           # cd extra/x11/fvwm
  75           # cvs tag -c -F -R CURRENT
  76
  77         NOTE: When tagging, you should be sure to ONLY tag the updated files,
  78         not the entire repository.  Otherwise, if parts of your checkout are
  79         out-of-date, you may actually be tagging an OLDER version of a file,
  80         reversing someone else's tag procedure.
  81
  82 3. The Process
  83
  84    3.1  Checkout/update your local repository from cvs.archlinux.org
  85    3.2  Make any changes you need to
  86    3.3  Put your new packages in your local staging directory on archlinux.org.
  87         Suggested syntax is:
  88           scp name-ver-rel.pkg.tar.gz you@archlinux.org:staging/extra/add
  89    3.4  Commit your changes (section 2.5)
  90    3.5  Update the CURRENT tags to new revisions (section 2.8)
  91    3.6  Log in to archlinux.org and run the /arch/db-extra script, which
  92         will re-generate the sync db and place it in /home/ftp/extra, then
  93         move the new/updated packages from your staging directory to the
  94         FTP tree.
  95    3.7  Remove any older versions of packages from /home/ftp/extra to
  96         save diskspace, they should be noted when the db generation script
  97         finishes.
  98
  99    Make sure you do things in this order, mixing them up can break things
 100    temporarily.  For example, if you remove older versions from the ftp
 101    tree before you update the database or update the database before
 102    uploading new packages, arch users trying to download the package at
 103    that time will get "file not found" errors.
 104
 105 4. Staging Directories
 106
 107    As mentioned in Section 3, packages need to be uploaded to the proper
 108    staging directory before running a db generation script.  The staging
 109    area (located in your home dir) looks like so:
 110
 111     staging
 112     |-- arch
 113     |   |-- add
 114     |   `-- del
 115     |-- extra
 116     |   |-- add
 117     |   `-- del
 118     |-- testing
 119     |   |-- add
 120     |   `-- del
 121     `-- unstable
 122         |-- add
 123         `-- del
 124
 125    As you can see, each repository has two staging directories: "add" and
 126    "del".  When you want to add or update a package, you'll place it in the
 127    "add" directory for the repository you're working in.  Then run the db-gen
 128    script.
 129
 130    When you want to remove a package, you will move the package OUT OF the FTP
 131    directory (eg, /home/ftp/extra/os/i686/) and INTO the "del" directory for
 132    the repository you're working in.  Once moved, you can run the db-gen
 133    script -- it will see that the file has left the FTP tree and will remove
 134    it from the package database.
 135
 136 5. Miscellaneous Stuff
 137
 138    5.1  If you are creating a daemon you need to include an rc.d startup
 139         script for it.  Look at /var/abs/daemons/esd for a simple example.
 140    5.2  Please include a line that says '# $Id: pkgmaint_guide.txt,v 1.3 2006/10/05 20:52:01 judd Exp $' at the top of each
 141         PKGBUILD.  This will be parsed by cvs during a commit, and replaced
 142         with user/timestamp data.
 143    5.3  Please do some rudimentary checks of the package before making it
 144         'live'.  Try installing it and see if there are any file conflicts.
 145         Check for dependencies by running 'ldd' against the binaries and
 146         looking through the .so files it requires.  For example,
 147         'ldd /usr/bin/gvim' returns a big list of libs, one of which is
 148         libgtk-x11-2.0.so.0, so gtk2 should be one of the dependencies for
 149         gvim.  Also, namcap is available in the extra repository.  Running it
 150         against a package will print dependancy warnings as well as possible
 151         configuration problems.  Namcap is not the final word, if ldd or
 152         runtime show otherwise, believe them instead.
 153    5.4  When creating a package description for a package, do not include
 154         the package name in a self-referencing way, as it is redundant.
 155         For example, "Nedit is a text editor for X11" could be simplified to
 156         "A text editor for X11".  Also try to keep the descriptions to ~80
 157         characters or less.
 158    5.5  When entering cvs log messages for new/upgraded packages, please use
 159         these tags so they can be easily parsed for changelog generation:
 160           if the package is upgrade use: 'upgpkg: pkgname newpkgver'
 161           if the package is new use:     'newpkg: pkgname newpkgver'
 162
 163
 164 $Id: pkgmaint_guide.txt,v 1.3 2006/10/05 20:52:01 judd Exp $