Instructions for new developers

1.  Using CVS

Introduction

This guide is not intended to be a manual on using CVS; for that, take a look at the CVS info page or http://www.gentoo.org/doc/en/cvs-tutorial.xml. Instead, this guide focuses specifically on using CVS and Repoman in Gentoo's ebuild tree.

Configuration

Typically, you'll want something along these lines in your ~/.cvsrc:

cvs -q -z0
diff -u -b -B
checkout -P
update -d -P

Finally, many people using CVS like to use compression (-z#). We ask that developers who are not on dialup connections please use -z0 - with the contents of our CVS repository and the load on our CVS server, you actually experience a speed _increase_ without compression.

Checking out

There are a few useful modules in Gentoo's CVS repository. Ebuilds are kept in the gentoo-x86 module. gentoo-src contains various projects - some useful, some inactive. gentoo contains the XML for the website, documentation, developer directories, developer pictures, and so on.

# cvs -d username@cvs.gentoo.org:/var/cvsroot co gentoo-x86

Before working in the tree at any time, it's always a good idea to do an update to check for changes and prevent conflicts. You can update in any subdirectory of the tree if you don't want to want for a tree-wide update, but from time to time it's a good idea to update your entire tree:

# cd gentoo-x86
# cvs update

Adding/Removing

Say you're ready to add a brand new package, foo, in app-misc:

# cd CVSROOT/app-misc (Replace CVSROOT with the location of your checked-out CVS tree.)
# cvs update (Always update before working in part of the tree!)
# mkdir foo
# cvs add foo (Here, we add the package directory foo to the CVS repository.)
# cd foo
# cp /path/to/foo-1.0.ebuild ./ (It's better to keep in-progress ebuilds in an overlay outside of your CVS tree.)
# repoman manifest
# cvs add foo-1.0.ebuild

Create and add a metadata.xml file with maintainer information. See the metadata guide for more information.

# echangelog "Initial commit. Ebuild written by me. Fixes bug #XXXXXX"

At this point, you're ready to commit (see the section on Commits below). But what if you want to remove foo-1.0 when foo-1.1 is out?

# cd CVSROOT/app-misc/foo
# cvs update
# cvs remove -f foo-1.0.ebuild

And now you're ready to commit (see the section on Commits below).

Commits

Always use repoman commit rather than cvs commit. Repoman is a quality assurance (QA) tool that performs basic checks and creates Manifests. If any part of repoman's output is unclear, please see man repoman. Additionally, you may tire of entering your key passphrase repeatedly; keychain (http://www.gentoo.org/proj/en/keychain.xml) can help you.

(Make sure there are no root-owned files present prior to running repoman.)
# repoman scan ("scan" scans the current directory for QA issues. "full" is more complete.)
# repoman commit ("commit" does a scan, then commits, while also updating the manifest. Make sure to use a verbose and useful cvs changelog message.)

2.  Miscellaneous

Putting files on mirrors

Distfiles are automatically fetched by the Gentoo Mirror System. You only need to monitor your distfiles for fetch errors. Please see the Distfiles Overview Guide for comprehensive instructions.

Mail and Web

Our infrastructure allows developers to manage their own mail. http://www.gentoo.org/proj/en/infrastructure/dev-email.xml contains instructions on configuring your @gentoo.org mail.

Developers have access to webhosting, http://dev.gentoo.org/~$YOURNAME. Please see the Webspace Configuration Guide for details.

Vacations

Often Gentoo developers go away on vacation, have to take a short leave for university exams or even go on a honeymoon. Although we applaud you for having a life outside Gentoo, we'd like to know you're gone and when you'll be back. When you leave, alert your immediate development group, whether that is gentoo-releng@gentoo.org or sparc@gentoo.org. Let them know you've gone and who can be contacted in your absence if packages need to be updated.

(When you leave, in your home directory:)
# touch ~/.away
# echo "I've gone to the mountains, will be away from June 29 - Aug 4th, \
contact zhen, cshields, or klieber in my absence." > ~/.away
(What this does is alert our script at http://dev.gentoo.org/devaway
of your absence. It's updated once an hour.)

(When you return:)
# rm ~/.away