Committer resources

This is information for developers who are committers to our repository.

Enrollment

• Athena account: MITKC staff will sponsor as appropriate. See http://web.mit.edu/accounts/www/getaccount.html for some overview information about Athena accounts.
• X.509 client certificate: Needed for RT access, among others. Information on how to obtain one is at http://web.mit.edu/ist/topics/certificates/index.html
• RT account
• Git access
• Daptiv access (for some contributors working on time-sensitive projects)
• Posting authorization to cvs-krb5 if you are going to commit stuff.

Where stuff is at

• Git URL: git.mit.edu:/git/krb5.git -- you may need to put "username@" in front if your local username is not the same as your Athena account name. Clone this instead of git@github.com:krb5/krb5.git when setting up your local repository in order to be able to push changes.
• SSH to athena.dialup.mit.edu if you want easy access to AFS, a UNIX shell, etc.
  • You'll need to set GSSAPIDelegateCredentials=yes in order to do passwordless login, because user home directories are in AFS, and the administrators didn't want to confuse users who logged in with Kerberos but couldn't access their files.
• RT https://krbdev.mit.edu/rt/ (or https://krbdev.mit.edu:444/rt/ if your browser doesn't deal with "optional" SSL client certificate verification)

Accessing git.mit.edu

The preferred way to access git.mit.edu is with GSSAPI krb5 authentication. It is not necessary to delegate credentials.

It is also possible to use publickey authentication. Because Athena account home directories are stored in AFS, there are some extra setup steps required to make sure that the sshd on git.mit.edu can read your public key:

• Your home directory and .ssh directory must allow list (but not read) access to unauthenticated users. This is generally the case by default.
• Your .ssh/authorized_keys file must be a link to a directory which allows read access to unauthenticated users. To set this up, you can ssh to athena.dialup.mit.edu and run:

   # mkdir $HOME/.ssh if it doesn't already exist.
   cd $HOME/.ssh
   mkdir pub
   fs sa pub system:anyuser rl
   # Move aside authorized_keys if it already exists.
   ln -s pub/authorized_keys authorized_keys

The contents of your key pair's .pub file should be placed into $HOME/.ssh/pub/authorized_keys.

Finally, you can authenticate to git.mit.edu using password authentication with your Athena password.

RT headers

If a commit makes a user-visible change, such as adding a new feature or fixing a user-visible bug in a previous release, it should be associated with an RT ticket. Do this by adding RT pseudo-headers at the end of the commit message, after a blank line. The most important header is "ticket:", which associates the commit with a ticket number. Add "tags: pullup" and "target_version: X.Y.Z" if the commit should be pulled up to a release branch. Here is an example:

   Use correct profile var in krb5_get_tgs_ktypes
   
   In r21879, when we converted to using KRB5_CONF macros for profile
   variable names, we made a typo in krb5_get_tgs_ktypes and erroneously
   started using default_tkt_enctypes instead of default_tgs_enctypes for
   TGS requests.  Fix the typo and return to the documented behavior.
   
   ticket: 7155
   target_version: 1.10.3
   tags: pullup

A ticket can only have one target_version, so if a fix needs to go into multiple releases, only list the most recent release in the target_version header, and then make a comment in the RT ticket (via the RT web interface) that the ticket should also be pulled up to the other releases.

New tickets

If you are creating a new ticket, run "ssh git.mit.edu krb5-rt-id" to reserve a ticket number, and put "ticket: NNNN (new)" in the commit message, substituting the ticket number for NNNN. The summary line of the commit will be used as the subject of the new ticket; if this is not what you want, you can use a "subject:" RT header to set the ticket subject, or you can change the subject afterwards in RT.

You can automate this process using a commit-msg hook. Drop the contents of the hook into .git/hooks/commit-msg and make it executable. Then you can put just "ticket: new" at the end of a commit message, and the hook will automatically reserve a ticket number and rewrite the header to "ticket: NNNN (new)". You should have some form of passwordless login to git.mit.edu set up for this to work transparently.

Pushing changes from contributors

When integrating code changes created by contributors, take note of the following:

• If the change is presented to you as one or more git commits, fetch the commit into your local git repository and then use git cherry-pick to make a copy of the relevant commits onto your master branch (or a topic branch). Do not use git merge.

• If the change is presented to you as a patch, make a commit from the patch and use the --author flag to git commit to set the commit author field to the author's name and email address.

• Review the changes as well as possible, and make sure they are organized into logical commits as required by our version control practices. Run the C style checker to identify possible style issues.

• Make sure the changes build and pass "make check".

• Add appropriate RT headers to the commit messages if appropriate.

• If you need to make significant changes to the commit or commit message, you can add a note to the end (before any RT headers) like:

   [ghudson@mit.edu: Stylistic changes, commit message]