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 "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.
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