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
    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-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDNc90vEP32OwsKkkHXQkUkkZYM155HZSoCIEQovICKQfeZ/MtEt2I4rINKlvmw+SEsbHvidiHRGk1V2c6/9aPjrzu7QkIkFZ5KgDyRDOrnQh2ZYwSU8AVRggb3lom616nYKhLw1S7y9rUlBDjhhSGr7GdCPKyQlzcfuIZLTR981TcRE1rUwOzwSZANh478U3eLIcF7ZB0Q+24l4sImcCh8o11sMXZpJB0i63m8sHr37JxvgOAxKLJ2rvUV0lq8F0NEr9zIpPPV0CCXOYS6UbkTaAAU5x6qFA+Yb5cRMVFno57A/jsi+1qGFpXFq05eVE76yczeKpa4b2Dd8f1yVx17

Newer SSH clients report the SHA256 instead:

RSA key fingerprint is SHA256:iNQwBCwUpvISdWAy4CnEE7xYNRJnNNvYH2uKoTDB6cU.

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 "your_email@example.com"
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 username@wip.pkgsrc.org:/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 username@wip.pkgsrc.org:/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.

Importing the package

Make sure you have a current checkout:

git pull -r

Add your package:

cd /usr/pkgsrc/wip
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 commit only what you intend to commit:

git status

If it looks good, commit and push:

git commit
git push

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 --committer-date-is-author-date

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 remove $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: Import foobar-1.2.3 as wip/foobar

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 wip/foobar to 1.2.4

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