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
• Posting authorization to cvs-krb5 if you are going to commit stuff.
• Coverity scan access

Where stuff is at

• Git URL: krbdev.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 krbdev.mit.edu

The preferred way to access krbdev.mit.edu is with GSSAPI krb5 authentication. It is not necessary to delegate credentials. publickey authentication can be set up if required.

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-next" 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-next
   tags: pullup

A ticket can multiple target_version values. If a fix needs to go into multiple releases, use a separate target_version header for each one.

New tickets

If you are creating a new ticket, run "ssh krbdev.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 krbdev.mit.edu set up for this to work transparently.

More about RT keywords

These are somewhat inconsistent and will need more editing:

• Additional detail about RT keywords
• Manipulating RT tickets using commits

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]