Contribute

Contributing to FreeIPA

1. Join mailing lists
2. Find us on IRC
3. Read developer docs
4. Install FreeIPA
5. Contributed Patches
6. Jump into our code and process
7. Edit this wiki or improve the documentation

Communication

Mailing Lists

The development of FreeIPA is done on the freeipa-devel mailing list. You can join at https://www.redhat.com/mailman/listinfo/freeipa-devel. Feel free to introduce yourself to the list and let us know what areas of development are of most interest to you.

Use freeipa-users mailing list to discuss deployment, configuration, and use of FreeIPA. It is the best place to ask "how to" questions and to share your experience with FreeIPA.

Subscribe to freeipa-interest mailing list for product-related announcements.

IRC

We also hang out on IRC at irc.freenode.net on the #freeipa channel.

Bug and Feature Tracking

• Bugs against released Fedora versions can be logged using the following Bugzilla link. As a component please select 'freeipa'.
• Bugs against released Red Hat Enterprise Linux versions of Identity Management product can be logged using the following Bugzilla link. As component please select the appropriate package. See package list for more details.
• We also use Trac for the upstream development, so all feature requests or bugs on the pre-releases should go here.

CLA

FreeIPA no longer requires a contributor license agreement (CLA). All contributed patches are licensed under the GPLv3+ license.

Development Process

Working with the Codebase

• Git Documentation: Information on using Git, our source control system of choice.
• C Coding Style Guide: Our style guide for C code used in FreeIPA.
• Python Coding Style Guide: Our style guide for Python code used in FreeIPA.
• Build: Instructions on how to build FreeIPA v1/2 from source
• Testing: Instructions on FreeIPA v2 tests
• Patch Format - Guidance about the patch format
  • You can also use scripts which enforce FreeIPA patch format automatically and even upload the script to Trac, e.g. these ones.
• Ticketing system - Upstream development tasks and issues

Considerations for FreeIPA related projects

Over the time it became apparent that contributions to the FreeIPA project can come not only in the form of reviews, configuration scripts, documents and patch submissions to the FreeIPA code base but also in a form of independent or integrated projects that deliver a big piece of functionality as a plugin. To make it easier to start and maintain these plugin projects we put together a list of general considerations that developers of the projects should keep in mind.

Source Repository

FreeIPA Server

The source repository for FreeIPA is stored in git. The code can be retrieved with the command:

git clone git://git.fedorahosted.org/git/freeipa.git

This will create the initial repository (named 'freeipa') in the current directory. Updating the repository can be accomplished with the command 'git pull' from within the repository. More information on GIT can be found at GitDocs.

You can also browse the source repository via the web.

System Security Services Daemon (IPA Client)

The source repository for the SSSD is stored in git. The code can be retrieved with the command:

git clone git://git.fedorahosted.org/git/sssd.git

You can also browse the source repository via the web.

Submitting Changes

Changes to the repository are submitted via patches on the freeipa-devel mailing list (see above for list information). The best way to prepare the patch is to commit the change locally and use 'git-format-patch -1 commit-id' to export the patch (where commit-id is the commit number of the checkin you want to send, use 'git log' to see it).

Commit Message Format

With git the first line of a commit message is what is displayed in the subject of a patch e-mail, so choose a short, concise description of what the patch does. Leave a blank line then include a more detailed description of the patch. If there is an associated trac ticket or bugzilla then include a reference to that.

Examples are:

Fix this test to work from source tree root

It would work if you ran the test from its location in tests/test_ipalib
but this isn't the most common method. If you want to run it individually
you can do:

$ ./make-test tests/test_ipalib/test_text.py

and

gpg2 requires --batch to use the --passphrase* arguments.

This was causing replica creation and installation to fail.

596446

Code Review

All patches must be submitted to the developer list for review. This is currently freeipa-devel@lists.fedoraproject.org. There is an exception to this rule called the "One Liner" rule - if the patch is trivial (e.g. only one line changed), it can be pushed upstream without a review. What means trivial? Use your best judgment.

A patch may not be pushed upstream until it has received approval on the devel mailing list.

You will also want to look at our Coding Style Guide

Tracking patches (Experimental)

We are experimentally using a Patchwork instance to keep track of patch status. If you want to track patches on your own just register yourself in Patchwork.

On patch(set) submission to the freeipa-devel list the patch is automatically entered in the list and marked as 'New'.

Here is how we mark patches at various stages:

• 1) Someone starts review:
  • Set delegate to the reviewer, change status to 'Under Review'

• 2) Patch needs more work:
  • Reviewer send comments to the list than changes status to 'Changes Requested'

• 3) New patch is sent to list:
  • If the old patch was reviewed 'Archive' old patch and go back to (1)
  • If the submitter just sent a new patch before review, the old one can simply be marked 'Superseeded'

• 4) Patch is accepted (ACK sent to devel list):
  • Change status to 'Accepted' and set delegate to the Acker

• 5) Patch is pushed:
  • Change status to 'pushed'

When status is change to 'pushed', 'superseeded' or the archive bit is set, the patch disappears from the default view and it is considered fully dealt with, no more action will be normally performed. If a patch needs to be resurrected from the dead, just use the extended search functions to find it and change back the status to whatever appropriate.

NOTE: currently Patchwork has the limitation that it will only show one patch if multiple patches are attched to an email. We are working on improving the situation, but currently we use patchwork just for tracking the patch(set) status so, please, do not send multiple mails with one patch per email, keep bundling patchsets as attachments to a single email.

Committing changes to git

The number one rule is to not hose the tree. We've had a bunch of problems in the past. gitk can be real ugly in places. The less we mess up the tree the better. Mistakes happen, just be as careful as you can.

The list of devs with upstream commit is short because it often requires some extra context to know which branches a patch needs to be pushed. It is sometimes not obvious from the ticket(s).

When pushing, one needs to do the following:

• Confirm that the patch has a valid ticket, and that the ticket is referenced in the patch
• Close the associated ticket(s). Include the commit hash for each branch. It is equally acceptable to include only the hash or a full URI to the upstream change.
• Add the hash to any associated BZs. If this corrects the problem then put the BZ into POST.

The list of users with commit should be evaluated periodically and trimmed as needed.

Wiki Editing

If you would like access to edit this Wiki, please send a request to the freeipa-devel mailing list and someone will create an account for you.

You can get some inspiration from our TODO list for Wiki and Documentation.