logo_kerberos.gif

Difference between revisions of "Contributing code"

From K5Wiki
Jump to: navigation, search
(Maintaining a github fork)
Line 15: Line 15:
 
== Maintaining a github fork ==
 
== Maintaining a github fork ==
   
If you are not yet fluent in git, the following instructions may help you with preparing a contribution using a github fork. These instructions assume that you want to keep your master branch clean (containing only commits from the krb5 master branch), and prepare your contributions on topic branches.
+
If you are not yet fluent in git, the following instructions may help you with preparing a contribution using a github fork. These instructions assume that you want to keep your local master branch clean and synchronized with the main krb5 master branch, and prepare your contributions on topic branches.
   
After you have forked the krb5 repository on the github web site, make a local clone with (replacing YOURNAME with your github username):
 
  +
To begin, create a github account if you don't already have one. Visit https://github.com/krb5/krb5 and click the "Fork" button to create a github fork.
   
git clone git@github.com:/YOURNAME/krb5.git
 
 
Make a local clone of the main github krb5 repository with (replacing YOURNAME with your github username):
  +
 
git clone git@github.com:krb5/krb5.git
 
cd krb5
 
cd krb5
git remote add upstream git://github.com/krb5/krb5
 
git fetch upstream
 
   
Within your local clone (where you'll be doing all of your work), your public github fork is now named "origin" and the upstream krb5 repository is named "upstream". You can keep the master branch of your local clone and public fork up to date with the following commands (you'll need a clean working copy for this):
 
  +
In this clone, add a remote for your github fork. (This remote can have any name you want, but we will assume you want to name it with your github username.)
   
git fetch upstream
 
 
git remote add YOURNAME git@github.com:YOURNAME/krb5.git
git checkout master
+
git fetch YOURNAME
git merge --ff-only upstream/master
 
git push origin master
 
   
The --ff-only flag will cause git merge to error out if you made any commits on the master branch by mistake.
 
  +
You can keep your local clone's master branch up to date with respect to the main krb5 master branch with:
  +
  +
git checkout master
  +
git pull origin master
   
 
Before making any changes, start a topic branch with (using "mangos" as an example name for the branch):
 
Before making any changes, start a topic branch with (using "mangos" as an example name for the branch):
Line 39: Line 42:
 
git commit -a
 
git commit -a
 
<enter your commit message>
 
<enter your commit message>
git push origin mangos
+
git push YOURNAME mangos
   
 
If your contribution fits naturally in one commit, you should now be ready to make a pull request from your github fork to the upstream krb5 repository using the github web site. If we have feedback on your pull request and you want to update your change, you can:
 
If your contribution fits naturally in one commit, you should now be ready to make a pull request from your github fork to the upstream krb5 repository using the github web site. If we have feedback on your pull request and you want to update your change, you can:
Line 47: Line 50:
 
git commit --amend -a
 
git commit --amend -a
 
<edit your commit message if necessary>
 
<edit your commit message if necessary>
git push origin +mangos
+
git push YOURNAME +mangos
   
 
The plus sign in the final command is necessary because you're overwriting the history of your mangos branch. This is normal for topic branches which aren't yet part of the established history of a project.
 
The plus sign in the final command is necessary because you're overwriting the history of your mangos branch. This is normal for topic branches which aren't yet part of the established history of a project.
   
If there are changes on the master branch that you want to make use of (or just to merge with), you can update the master branch using the instructions above and then rebase your topic branch with:
+
After you begin (or finish) work on your topic branch, changes will probably have been made to the main krb5 master branch. To keep up with these changes, you can update your master branch (as described above), then rebase your topic branch onto the updated master branch and then synchronize that to your github fork:
   
 
git rebase master mangos
 
git rebase master mangos
git push origin +mangos
+
git push YOURNAME +mangos
   
If your contribution naturally breaks down into multiple logical commits, then you will likely need to familiarize yourself with git's tools for editing branch history, probably by learning how to use "git rebase -i". As above, use "git push origin +mangos" to update your github fork's copy of the topic branch after you are done editing its history.
+
If your contribution naturally breaks down into multiple logical commits, then you will likely need to familiarize yourself with git's tools for editing branch history, probably by learning how to use "git rebase -i". As above, use "git push YOURNAME +mangos" to update your github fork's copy of the topic branch after you are done editing its history.
   
 
If you want to delete your topic branch in the local repository and github fork, you can do so with:
 
If you want to delete your topic branch in the local repository and github fork, you can do so with:
   
 
git branch -D mangos
 
git branch -D mangos
git push origin :mangos
+
git push YOURNAME :mangos
   
(Read the second command as "into the origin repository, push <empty branchname> onto the mangos branch", which causes it to be deleted.)
+
(Read the second command as "push <empty branchname> onto the mangos branch", which causes it to be deleted.)

Revision as of 13:59, 27 November 2012

The MIT krb5 team is willing to accept code contributions in a variety of forms, but the most preferred method is a pull request for https://github.com/krb5/krb5. Please follow the coding style guidelines, including the version control practices, and use the style checker script to help minimize style issues.

By default, we will commit code contributions using your name and email address in the git "author" metadata field and a committer's name and email in the git "committer" metadata field. If we make changes to the contribution when committing it, we will note that in square brackets in the commit message. If you prefer otherwise, let us know.

For larger contributions such as new features, we have some additional requirements:

  • The code must be available under a permissive license such as the 2-clause BSD license used for the project itself. We encourage, but do not require, copyright to be assigned to MIT to avoid adding to the number of licenses in our notice file. (All we need to consider copyright assigned is an unambiguous statement in email.)
  • There should be a project proposal with a description of the use case and design of the change.
  • There should be an opportunity for community feedback on the krbdev@mit.edu mailing list.
  • There must be a way to test the new functionality. Automated test cases integrated with "make check" are required unless that would be unusually difficult due to the nature of the change.
  • There should be documentation of the new functionality (under doc/rst_source in the source tree).

In some cases we may be willing to fulfill these requirements ourselves, but that will postpone the acceptance of the contribution until we have the resources to do so. We also require a careful code review of any new code contribution by a core team member, and may have changes to request or may make changes ourselves.

Maintaining a github fork

If you are not yet fluent in git, the following instructions may help you with preparing a contribution using a github fork. These instructions assume that you want to keep your local master branch clean and synchronized with the main krb5 master branch, and prepare your contributions on topic branches.

To begin, create a github account if you don't already have one. Visit https://github.com/krb5/krb5 and click the "Fork" button to create a github fork.

Make a local clone of the main github krb5 repository with (replacing YOURNAME with your github username):

   git clone git@github.com:krb5/krb5.git
   cd krb5

In this clone, add a remote for your github fork. (This remote can have any name you want, but we will assume you want to name it with your github username.)

   git remote add YOURNAME git@github.com:YOURNAME/krb5.git
   git fetch YOURNAME

You can keep your local clone's master branch up to date with respect to the main krb5 master branch with:

   git checkout master
   git pull origin master

Before making any changes, start a topic branch with (using "mangos" as an example name for the branch):

   git checkout -b mangos master

After making changes, make sure to "git add" any new files and then run:

   git commit -a
   <enter your commit message>
   git push YOURNAME mangos

If your contribution fits naturally in one commit, you should now be ready to make a pull request from your github fork to the upstream krb5 repository using the github web site. If we have feedback on your pull request and you want to update your change, you can:

   git checkout mangos
   <make your changes>
   git commit --amend -a
   <edit your commit message if necessary>
   git push YOURNAME +mangos

The plus sign in the final command is necessary because you're overwriting the history of your mangos branch. This is normal for topic branches which aren't yet part of the established history of a project.

After you begin (or finish) work on your topic branch, changes will probably have been made to the main krb5 master branch. To keep up with these changes, you can update your master branch (as described above), then rebase your topic branch onto the updated master branch and then synchronize that to your github fork:

   git rebase master mangos
   git push YOURNAME +mangos

If your contribution naturally breaks down into multiple logical commits, then you will likely need to familiarize yourself with git's tools for editing branch history, probably by learning how to use "git rebase -i". As above, use "git push YOURNAME +mangos" to update your github fork's copy of the topic branch after you are done editing its history.

If you want to delete your topic branch in the local repository and github fork, you can do so with:

   git branch -D mangos
   git push YOURNAME :mangos

(Read the second command as "push <empty branchname> onto the mangos branch", which causes it to be deleted.)