Chapter 23. Submitting and Committing

Table of Contents

23.1. Submitting binary packages
23.2. Submitting source packages (for non-NetBSD-developers)
23.3. General notes when adding, updating, or removing packages
23.4. Commit Messages
23.5. Committing: Adding a package to CVS
23.6. Updating a package to a newer version
23.7. Renaming a package in pkgsrc
23.8. Moving a package in pkgsrc

23.1. Submitting binary packages

Our policy is that we accept binaries only from pkgsrc developers to guarantee that the packages don't contain any trojan horses etc. This is not to annoy anyone but rather to protect our users! You're still free to put up your home-made binary packages and tell the world where to get them. NetBSD developers doing bulk builds and wanting to upload them please see Chapter 8, Creating binary packages for everything in pkgsrc (bulk builds).

23.2. Submitting source packages (for non-NetBSD-developers)

First, check that your package is complete, compiles and runs well; see Chapter 14, Creating a new pkgsrc package from scratch and the rest of this document. Next, generate an uuencoded gzipped tar(1) archive that contains all files that make up the package. Finally, send this package to the pkgsrc bug tracking system, either with the send-pr(1) command, or if you don't have that, go to the web page https://www.NetBSD.org/support/send-pr.html, which contains some instructions and a link to a form where you can submit packages. The sysutils/gtk-send-pr package is also available as a substitute for either of the above two tools.

In the form of the problem report, the category should be pkg, the synopsis should include the package name and version number, and the description field should contain a short description of your package (contents of the COMMENT variable or DESCR file are OK). The uuencoded package data should go into the fix field.

If you want to submit several packages, please send a separate PR for each one, it's easier for us to track things that way.

Alternatively, you can also import new packages into pkgsrc-wip (pkgsrc work-in-progress); see the homepage at https://pkgsrc.org/wip/ for details.

23.3. General notes when adding, updating, or removing packages

Please note all package additions, updates, moves, and removals in pkgsrc/doc/CHANGES-YYYY. It's very important to keep this file up to date and conforming to the existing format, because it will be used by scripts to automatically update pages on www.NetBSD.org and other sites. Additionally, check the pkgsrc/doc/TODO file and remove the entry for the package you updated or removed, in case it was mentioned there.

When the PKGREVISION of a package is bumped, the change should appear in pkgsrc/doc/CHANGES-YYYY if it is security related or otherwise relevant. Mass bumps that result from a dependency being updated should not be mentioned. In all other cases it's the developer's decision.

There is a make target that helps in creating proper CHANGES-YYYY entries: make changes-entry. It uses the optional CTYPE and NETBSD_LOGIN_NAME variables. The general usage is to first make sure that your CHANGES-YYYY file is up-to-date (to avoid having to resolve conflicts later-on) and then to cd to the package directory. For package updates, make changes-entry is enough. For new packages, or package moves or removals, set the CTYPE variable on the command line to "Added", "Moved", or "Removed". You can set NETBSD_LOGIN_NAME in mk.conf if your local login name is not the same as your NetBSD login name. The target also automatically removes possibly existing entries for the package in the TODO file. Don't forget to commit the changes, e.g. by using make commit-changes-entry! If you are not using a checkout directly from cvs.NetBSD.org, but e.g. a local copy of the repository, you can set USE_NETBSD_REPO=yes. This makes the cvs commands use the main repository.

23.4. Commit Messages

For several years, there have been mirrors of pkgsrc in fossil, git, and hg. Standard practise when using these tools is to make the first line of a commit message function as a summary that can be read without the rest, such as is commonly done with "git log --oneline". For this reason, we have the following guidelines for pkgsrc commit messages:

  • Start the commit message with a line that explains the big picture in 65 characters or less. When a commit is for one package, include the name of the package. For updates, include the version to which it is updated.

  • Leave the next line empty.

  • Then come the details for the commit (changes in that package, reason for a change) and any relevant PRs. Wrap this section.

Here is an example:

  libxslt: update to 1.0.30

  Changes since 1.0.29:
  ...
  

Here is another example:

  mk/bsd.pkg.mk: enable SSP by default on NetBSD

  (rationale)
  

Commit messages are final: no cvs admin is allowed on the pkgsrc repository to change commit messages.

23.5. Committing: Adding a package to CVS

This section is only of interest for pkgsrc developers with write access to the pkgsrc repository.

When the package is finished, cvs add the files. Start by adding the directory and then files in the directory. Don't forget to add the new package to the category's Makefile. Make sure you don't forget any files; you can check by running cvs status. An example:

$ cd .../pkgsrc/category
$ cvs add pkgname
$ cd pkgname
$ cvs add DESCR Makefile PLIST distinfo buildlink3.mk patches
$ cvs add patches/p*
$ cvs status | less
$ cvs commit
$ cd ..
$ vi Makefile # add SUBDIRS+=pkgname line
$ cvs commit Makefile
$ cd pkgname
$ make CTYPE=Added commit-changes-entry

The commit message of the initial import should include part of the DESCR file, so people reading the mailing lists know what the package is/does.

Also mention the new package in pkgsrc/doc/CHANGES-20xx.

Previously, cvs import was suggested, but it was much easier to get wrong than cvs add.

23.6. Updating a package to a newer version

Please always put a concise, appropriate and relevant summary of the changes between old and new versions into the commit log when updating a package. There are various reasons for this:

  • A URL is volatile, and can change over time. It may go away completely or its information may be overwritten by newer information.

  • Having the change information between old and new versions in our CVS repository is very useful for people who use either cvs or anoncvs.

  • Having the change information between old and new versions in our CVS repository is very useful for people who read the pkgsrc-changes mailing list, so that they can make tactical decisions about when to upgrade the package.

Please also recognize that, just because a new version of a package has been released, it should not automatically be upgraded in the CVS repository. We prefer to be conservative in the packages that are included in pkgsrc - development or beta packages are not really the best thing for most places in which pkgsrc is used. Please use your judgement about what should go into pkgsrc, and bear in mind that stability is to be preferred above new and possibly untested features.

23.7. Renaming a package in pkgsrc

Renaming packages is not recommended.

When renaming packages, be sure to fix any references to the old name in other Makefiles, options, buildlink files, etc.

Also, when renaming a package, please add the package name and version pattern(s) of the previous package to SUPERSEDES. This may be repeated for multiple renames. The new package would be an exact replacement. Example:

SUPERSEDES+=    p5-IO-Compress-Zlib<2.017
SUPERSEDES+=    optcomp-[0-9]*

Note that successor in the CHANGES-YYYY file doesn't necessarily mean that it supersedes, as that successor may not be an exact replacement but is a suggestion for the replaced functionality.

23.8. Moving a package in pkgsrc

It is preferred that packages are not renamed or moved, but if needed please follow these steps.

  1. Make a copy of the directory somewhere else.

  2. Remove all CVS dirs.

    Alternatively to the first two steps you can also do:

    % cvs -d user@cvs.NetBSD.org:/cvsroot export -D today pkgsrc/category/package

    and use that for further work.

  3. Fix CATEGORIES and any DEPENDS paths that just did ../package instead of ../../category/package.

  4. In the modified package's Makefile, consider setting PREV_PKGPATH to the previous category/package pathname. The PREV_PKGPATH can be used by tools for doing an update using pkgsrc building; for example, it can search the pkg_summary(5) database for PREV_PKGPATH (if no SUPERSEDES) and then use the corresponding new PKGPATH for that moved package. Note that it may have multiple matches, so the tool should also check on the PKGBASE too. The PREV_PKGPATH probably has no value unless SUPERSEDES is not set, i.e. PKGBASE stays the same.

  5. cvs import the modified package in the new place.

  6. Check if any package depends on it:

    % cd /usr/pkgsrc
    % grep /package */*/Makefile* */*/buildlink*
  7. Fix paths in packages from step 5 to point to new location.

  8. cvs rm (-f) the package at the old location.

  9. Remove from oldcategory/Makefile.

  10. Add to newcategory/Makefile.

  11. Commit the changed and removed files:

    % cvs commit oldcategory/package oldcategory/Makefile newcategory/Makefile

    (and any packages from step 5, of course).