Contributing to FreeIPA: A Guide for New Contributors

Welcome to FreeIPA Development!

FreeIPA thrives because of its vibrant open-source community. Whether you’re a developer, technical writer, system administrator, or enthusiast, there are many ways to contribute. This guide will help you get started.

Why Contribute?

Contributing to FreeIPA offers numerous benefits:

Learn: Deepen your understanding of identity management, Kerberos, LDAP, and PKI
Impact: Your contributions benefit thousands of users worldwide
Network: Connect with security and identity management professionals
Career: Build your portfolio with real-world open-source contributions
Give Back: Support the free software community

Ways to Contribute

1. Code Contributions

Getting Started with Development

Set up your development environment:

# Clone the repository
git clone https://github.com/freeipa/freeipa.git
cd freeipa

# Install development dependencies (Fedora/RHEL/CentOS)
sudo dnf builddep freeipa.spec

# Install additional tools
sudo dnf install git-review tox python3-pytest

# Configure git
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

Understanding the Codebase

FreeIPA’s structure:

freeipa/
├── client/           # Client-side tools
├── install/          # Installation scripts
├── ipaclient/        # Client Python library
├── ipalib/           # Core library
├── ipapython/        # Utility modules
├── ipaserver/        # Server components
├── ipatests/         # Test suite
└── doc/              # Documentation

Key technologies:

Python: Primary development language
JavaScript: Web UI (Dojo framework)
C: Some performance-critical components
Shell: Installation and utility scripts

Finding Issues to Work On

Start with beginner-friendly issues:

Visit GitHub Issues
Filter by labels: good first issue, help wanted
Review the issue description and comments
Comment on the issue expressing interest

Example good first issues:

Documentation improvements
Test coverage enhancement
Code cleanup and refactoring
Bug fixes with clear reproduction steps

Development Workflow

# Create a feature branch
git checkout -b fix-issue-1234

# Make your changes
vim ipaclient/remote_plugins/2_156/user.py

# Run tests
pytest ipatests/test_xmlrpc/test_user_plugin.py

# Lint your code
tox -e lint

# Commit with descriptive message
git commit -am "Fix user-add validation for special characters

The user-add command was failing when usernames contained
underscores. This commit adds proper validation and escaping.

Fixes: #1234"

# Push to your fork
git push origin fix-issue-1234

Submitting a Pull Request

Push your branch to your fork
Open pull request on GitHub
Fill out the PR template completely
Link related issues
Request review from maintainers
Address review comments
Celebrate when merged!

Code Style Guidelines

Follow project conventions:

Python:

# Use PEP 8 style
# 4-space indentation
# Maximum line length: 79 characters
# Descriptive variable names

def add_user(username, first_name, last_name, **kwargs):
    """
    Add a new user to FreeIPA.

    :param username: User login name
    :param first_name: User's first name
    :param last_name: User's last name
    :param kwargs: Additional user attributes
    :return: User object
    """
    # Implementation
    pass

JavaScript:

// Use 4-space indentation
// Semicolons required
// camelCase for variables

define(['dojo/_base/declare', 'dojo/_base/lang'],
function(declare, lang) {
    return declare(null, {
        addUser: function(username, firstName, lastName) {
            // Implementation
        }
    });
});

2. Documentation

Documentation is critical and always needs improvement.

Types of Documentation

User Guides: Step-by-step tutorials
Administrator Guides: Deployment and management
Developer Documentation: API references, architecture
Wiki Pages: Tips, troubleshooting, FAQs

Contributing Documentation

# Documentation is in the doc/ directory
cd freeipa/doc

# Edit documentation (reStructuredText format)
vim designs/new-feature.rst

# Build documentation locally
make html

# View in browser
firefox _build/html/index.html

Documentation Style Guide

Use clear, concise language
Include examples for commands
Explain the “why” not just the “how”
Test all commands before documenting
Use consistent formatting
Add screenshots where helpful

3. Testing

Help improve FreeIPA quality through testing.

Manual Testing

Test new features and bug fixes:

Set up test environment (VM recommended)
Install FreeIPA from source or testing repository
Follow test plans for new features
Report bugs with detailed reproduction steps

Automated Testing

Write test cases:

# ipatests/test_xmlrpc/test_user_plugin.py

import pytest
from ipalib import errors

class TestUserPlugin:
    def test_user_add_with_underscore(self):
        """Test that usernames with underscores are accepted."""
        username = 'test_user'

        # Add user
        result = api.Command['user_add'](
            username,
            givenname='Test',
            sn='User'
        )

        # Verify
        assert result['result']['uid'][0] == username

        # Cleanup
        api.Command['user_del'](username)

    def test_user_add_invalid_chars(self):
        """Test that invalid characters are rejected."""
        username = 'test@user'

        with pytest.raises(errors.ValidationError):
            api.Command['user_add'](
                username,
                givenname='Test',
                sn='User'
            )

Run tests:

# Run specific test
pytest ipatests/test_xmlrpc/test_user_plugin.py::TestUserPlugin::test_user_add_with_underscore

# Run all user tests
pytest ipatests/test_xmlrpc/test_user_plugin.py

# Run with coverage
pytest --cov=ipaclient.plugins.user

4. Community Support

Help other users succeed with FreeIPA.

Mailing Lists

Subscribe to and participate in:

freeipa-users: User questions and discussions
freeipa-devel: Development discussions
freeipa-announce: Release announcements

When answering questions:

Be patient and friendly
Ask for details (logs, configurations)
Provide step-by-step solutions
Share relevant documentation links
Follow up to ensure issue resolved

IRC/Matrix

Join real-time discussions:

IRC: #freeipa on irc.libera.chat
Matrix: #freeipa:fedoraproject.org

IRC etiquette:

Don’t ask to ask, just ask
Be patient for responses
Use paste services for logs
Search logs for previous discussions

5. Bug Reporting

Quality bug reports are valuable contributions.

Writing Good Bug Reports

Include:

Summary: Brief, descriptive title
Version: FreeIPA version and OS
Steps to Reproduce: Exact commands
Expected Behavior: What should happen
Actual Behavior: What actually happens
Logs: Relevant log excerpts
Environment: Hardware, network setup

Example:

Title: user-add fails with AttributeError for users with underscores

Version: FreeIPA 4.9.10 on Fedora 36

Steps to Reproduce:
1. Run: ipa user-add test_user --first=Test --last=User
2. Observe error

Expected: User created successfully
Actual: AttributeError: 'str' object has no attribute 'decode'

Logs:
2024-03-01 10:15:32,123 ERROR user_add: AttributeError
  File "/usr/lib/python3.10/site-packages/ipaserver/plugins/user.py", line 234
    username.decode('utf-8')
AttributeError: 'str' object has no attribute 'decode'

Environment:
- Server: Fedora 36, FreeIPA 4.9.10
- Client: RHEL 8.6, FreeIPA 4.9.8
- Single server deployment

6. Translation

Help make FreeIPA accessible globally.

Translation Platform

FreeIPA uses Weblate for translations:

Visit FreeIPA on Weblate
Select your language
Translate strings
Submit for review

Translation Guidelines

Maintain consistent terminology
Preserve formatting placeholders (%s, {0})
Consider context and technical accuracy
Ask for clarification when needed

Development Best Practices

Code Review

When reviewing others’ code:

Be constructive and respectful
Explain reasoning for suggestions
Acknowledge good solutions
Test the changes locally
Approve only when confident

Git Commit Messages

Write clear commit messages:

Short (50 chars or less) summary

More detailed explanation if needed. Wrap at 72 characters.
Explain the problem that this commit solves and why this
approach was chosen.

- Bullet points okay
- Use present tense ("Add feature" not "Added feature")

Fixes: https://github.com/freeipa/freeipa/issues/1234
Signed-off-by: Your Name <your.email@example.com>

Security Considerations

When contributing security-related code:

Never commit credentials or keys
Avoid introducing vulnerabilities
Follow secure coding practices
Consider attack vectors
Document security implications

Continuous Integration

FreeIPA uses CI to test changes:

Azure Pipelines for automated testing
PRs must pass CI checks
Review CI failures and fix
Don’t merge with failing tests

Getting Help

Resources

Documentation: https://www.freeipa.org/page/Documentation
Wiki: https://www.freeipa.org/page/Main_Page
GitHub: https://github.com/freeipa/freeipa
Mailing Lists: https://lists.fedoraproject.org/archives/list/freeipa-users@lists.fedorahosted.org/

Asking Questions

When stuck:

Search existing documentation and issues
Check mailing list archives
Ask on IRC/Matrix for quick help
Post to mailing list for detailed questions
Be specific and provide context

Finding a Mentor

New contributors can benefit from mentorship:

Express interest on the mailing list
Attend community meetings
Ask experienced contributors for guidance
Participate in online discussions

Community Events

Hackfests

FreeIPA holds periodic hackfests:

In-person or virtual coding sessions
Work on features collaboratively
Network with other developers
Learn from maintainers

Conference Talks

Share FreeIPA knowledge:

Submit talks to conferences
Present at local user groups
Write blog posts
Create video tutorials

Recognition

Contributors are recognized through:

Git History: Your commits are permanent
Release Notes: Major contributions highlighted
Community Thanks: Appreciation in announcements
Maintainer Status: Path to becoming a maintainer

Code of Conduct

FreeIPA follows the Fedora Code of Conduct:

Be respectful and inclusive
Welcome newcomers
Focus on what’s best for the community
Show empathy towards others
Report harassment or violations

Next Steps

Ready to contribute? Here’s how to start:

Set up environment: Clone repo, install dependencies
Find an issue: Look for good first issue label
Introduce yourself: Post on mailing list
Make first contribution: Start small
Iterate: Learn from feedback, improve

Contribution Checklist

Before submitting:

Conclusion

Every contribution matters, whether it’s a single line of code, a documentation fix, or helping another user. The FreeIPA community values all contributions and looks forward to working with you.

Welcome to the team!

Contact

Mailing List: freeipa-devel@lists.fedorahosted.org
IRC: #freeipa on irc.libera.chat
GitHub: https://github.com/freeipa/freeipa

Let’s build great identity management software together!