pkgsrc/ wip/ users

The pkgsrc-wip project -- committer access

Getting access

If you're interested in committing packages, send mail to Thomas Klausner with your public SSH key, suggested user name and perhaps ideas for your first packages.

Setup

Generating and using a separate SSH key

To generate an SSH key it is suggested to use RSA with at least 1024 bits and a passphrase via ssh-keygen(1). We can select RSA as the type of the key via the -t rsa and the number of bits (we choose 2048 bits) via the -b option:

$ ssh-keygen -b 2048 -t rsa
Generating public/private rsa key pair.
Enter file in which to save the key (/home/user/.ssh/id_rsa): /home/user/.ssh/pkgsrc-wip-id_rsa
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/user/.ssh/pkgsrc-wip-id_rsa.
Your public key has been saved in /home/user/.ssh/pkgsrc-wip-id_rsa.pub.
[...]

The pkgsrc-wip-id_rsa is the private key and the pkgsrc-wip-id_rsa.pub is the public key. Please remember to just attach the public key pkgsrc-wip-id_rsa.pub when you are sending your email to request an user account!

In order to use it adjust the ~/.ssh/config as follow, adding:

[...]
Host wip.pkgsrc.org
    PubkeyAuthentication yes
    IdentitiesOnly yes
    IdentityFile ~/.ssh/pkgsrc-wip-id_rsa
[...]

You can then use ssh-agent(1) in order to not type the SSH key password each time.

The SSH server fingerprint is:

wip.pkgsrc.org ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDiRTHbOjF/SUgqkbZjddDZDjasIbFpoQTRzUVnAoJJw

Setting up git

In contrast to pkgsrc itself, pkgsrc-wip uses git as source control system. Install devel/git.

Then, set the email address and user name used in the commits this way:

git config --global user.email "[email protected]"
git config --global user.name "Your Name"

If you just want to set this up for wip, run this command inside the repository and leave out the --global.

Getting via git -- with an account

If you have no clone yet, use:

cd /usr/pkgsrc/
git clone [email protected]:/pkgsrc-wip.git wip

Of course, username is your username.

If you already have the anonymous checkout, you can re-use that, but have to change the origin:

git remote set-url origin [email protected]:/pkgsrc-wip.git

Keeping up-to-date

Upgrading your clone

Just invoke the following:

cd /usr/pkgsrc/wip
git pull -r

Creating packages

Creating and testing

If you haven't read it yet, take a look at the pkgsrc Guide (also in /usr/pkgsrc/doc/pkgsrc.txt).

Create a package.

Test it with pkglint -- not all reported warnings and errors need to be fixed, but you should try to at least understand the reported ones. In case of trouble, ask on the tech-pkg mailing list.

Differences from pkgsrc

A wip package should have a file COMMIT_MSG that contains exactly the text that should be used if importing the package to main pkgsrc, or in updating the main pkgsrc package from the wip version. Someone with main pkgsrc write access should be able to copy bits and do cvs commit -F COMMIT_MSG. This means that it should start off with "category/pkgpath: Add foo version 1.2.3" and then contain the rest. Or "category/pkgpath: Update foo to 4.5.6", a blank line, a description of packaging changes, another blank line, and a summary of what upstream should have put in NEWS.

Generally, for a package that also exists in pkgsrc, when you update a wip package to a new version, you should also modify COMMIT_MSG so that it additionally includes the upstream changes for the new version. If the package is not in pkgsrc, then COMMIT_MSG says "Add" and new upstream changes are not necessary. The point is that COMMIT_MSG should always be relative to what is in pkgsrc.

Unless you are a TNF member and intend to commit your own package later, the committer will be different than the packager. It is appropriate to add an additional section, typically before packaging changes, either "Packaged in wip by Alyssa P. Hacker." or "Update prepared in wip by Ben Bitdiddle".

Importing the package

Make sure you have a current checkout. Note that "git pull" will by default create backwards merge commits; these are messy and not allowed. Therefore you must rebase any local commits on top of upstream.

cd /usr/pkgsrc/wip
git pull -r

Add your package:

git add newpkg

where newpkg is the name of your new package.

Then add the directory to the list of all subdirectories:

vi Makefile
# add "SUBDIR+=<TAB>newpkg"
git add Makefile

Check that you are about to commit only what you intend to commit:

git status

If it looks good, commit, review and push:

git commit
git log -p -1
git push

If the commit is not correct, fix it with "git commit --amend".

See below for commit message rules.

If you get a permission error while pushing the changes, make sure you checked out the repository with your user permissions and are not trying to push to the anonymous git repository.

You can also use the wip/import-package.sh script instead.

If you find out that there were changes in between your last pull and the push, please rebase your changes.

git rebase -i

Further changes

Include a TODO file detailing what you think is missing or needs more work, or just noting that it's finished.

For any further changes to the package, go to the newpkg directory, edit,

git add .

or

git rm $SOMETHING

to remove unused/unneeded files, then

git status
git commit
git push

If you have questions, or want review for a finished package, ask on the tech-pkg mailing list. If other people with enough knowledge judge your package ready, it'll probably get committed to the main pkgsrc repository soon afterwards -- enjoy your fame in that case!

You will find pkgsrc.se very useful while working on packages. Also try the tools that come with meta-pkgs/pkg_developer.

Notes regarding commit messages

In git(1) the first line of a commit message represents its subject and should consists of a short single line summary of the changes. It is separated from the body (where changes are discussed more in detail) with a newline, e.g.:

Short summary of the commit message (subject)

More information regarding the changes...
...that probably will need multiple lines.
[...]

Please remember that the subject of the commit message will automatically become also the Subject: of the corresponding email sent to the pkgsrc-wip-changes mailing list. A good subject will help other people involved in pkgsrc-wip to track your changes.

It is suggested to respect the following practices for the various use cases.

Import of a package named foobar, version 1.2.3

foobar: Add foobar-1.2.3

Various information regarding the foobar package... Usually the contents
of the wip/foobar/DESCR file.

Update of a package named foobar to version 1.2.4

foobar: Update to 1.2.4

Packaging changes: [omit if empty]
 * Explain changes made to how the package is built

Upstream changes:
 * List of the changes (usually available by an upstream changelog)

Miscellaneous fixes of a package named foobar

foobar: Fix PLIST issues with the "buz" option

TODO file changes

TODO: foobar update was done

Project contact

Thomas Klausner