Contribute¶
There are many ways you can contribute to the System Security Services Daemon. This page should provide some basic pointers.
SSSD development discussions occur either on the SSSD development (sssd-devel) mailing list or on the #sssd IRC channel on freenode. Keep in mind that SSSD developers are spread across different time zones, which makes mailing list preferred communication channel if you wish to reach the entire team.
The SSSD originated as a sister-project to FreeIPA, so we share many pieces. Contributing to FreeIPA may also help SSSD and vice versa.
If you want to file a bug or enhancement request, please log in with your Fedora Account System credentials. If you do not have a Fedora Account, you can register for one at https://admin.fedoraproject.org/accounts/. There is dedicated page about bug reporting.
Contribution Policy¶
All source code committed to the SSSD is assumed to be made available under the GPLv3+ license unless the submitter specifies another license at that time. The upstream SSSD maintainers reserve the right to refuse a submission if the license is deemed incompatible with the goals of the project.
Source Code Repository¶
For the SSSD project, we use the Git source control system.
Hosted on Pagure are the documentation, the issue tracker, and the referential repository:
https://pagure.io/SSSD/sssd.git
SSSD’s repository on Pagure is mirrored to GitHub and maintained as read-only instance:
https://github.com/SSSD/sssd
The preferred way for sending patches is to create pull requests either on Pagure or GitHub. You can also e-mail your patch as an attachment to the sssd-devel mailing list. A guide for a GitHub workflow is available. The paragraphs below assume you are using Pagure.
Tasks for newcomers¶
We try to mark tickets that don’t require too much existing knowledge
with the easyfix keyword in our issue tracker. We also prepared a query that
lists the easy fixes.
Before starting the work on any of these tickets, it might be a good idea
to contact the SSSD developers on the sssd-devel
mailing list and check if the ticket is still valid or ask for guidance in
general.
Getting the source¶
To check out the latest SSSD sources, install git on your system (Instructions are for Fedora, you may need to use a platform-specific installation mechanism for other OSes).
sudo dnf -y install git
You can find an excellent tutorial for using git.
The first time, you will want to configure git with your name and email address for patch attribution:
git config --global user.name "GIVENNAME SURNAME"
git config --global user.email "username@domain.com"
You can enable syntax highlighting at the console (for git commands such
as ‘git status’ and ‘git diff’) by setting:
git config --global color.ui auto
And if you would like to have a graphical tool for resolving merge conflicts, you can install and set up meld:
sudo dnf -y install meld
git config --global merge.tool meld
It can be invoked with
git mergetool
Once that’s done, you can clone our upstream git repository with
git clone https://pagure.io/SSSD/sssd.git
This will create a new subdirectory ‘sssd’ in the current directory which will contain the current master sources. All development should be done first against the master branch, then backported to one of the stable branches if necessary.
You can also enable the commit template by:
git config commit.template .git-commit-template
Building SSSD¶
Starting with SSSD 1.10 beta, we now include a set of helper aliases and environment variables in SSSD to simplify building development versions of SSSD on Fedora. To take advantage of them, use the following command:
. /path/to/sssd-source/contrib/fedora/bashrc_sssd
To build SSSD from source, follow these steps:
Install necessary tools
# when using yum sudo yum -y install rpm-build yum-utils libldb-devel # when using dnf sudo dnf -y install rpm-build dnf-plugins-core libldb-devel
Create source rpm (run from git root directory)
contrib/fedora/make_srpm.sh
Install SSSD dependencies
# when using yum sudo yum-builddep rpmbuild/SRPMS/sssd-*.src.rpm # when using dnf sudo dnf builddep rpmbuild/SRPMS/sssd-*.src.rpm
If you plan on working with the SSSD source often, you may want to add
the following to your ~/.bashrc file:
if [ -f /path/to/sssd-source/contrib/fedora/bashrc_sssd ]; then
. /path/to/sssd-source/contrib/fedora/bashrc_sssd
fi
You can now produce a Debug build of SSSD by running:
cd /path/to/sssd-source
reconfig && chmake
The reconfig alias will run autoreconf -if, create a parallel
build directory named after your CPU architecture (e.g. x86_64) and
then run the configure script with the appropriate options for
installing on a Fedora system with all experimental features enabled.
The chmake alias will then perform the build (with build messages
suppressed except on warning or error) as well as build and run tests.
Finally, assuming you have sudo privilege, you can run the
sssinstall alias to install this debug build onto the build machine.
sssinstall && echo build install successful
You can also directly build rpm packages for Fedora or CentOS using make target rpms or prerelease-rpms. The second version will create rpm packages with date and git hash in package release.
make rpms
#snip
Wrote: /dev/shm/gcc/rpmbuild/RPMS/x86_64/sssd-libwbclient-1.13.90-0.fc23.x86_64.rpm
Wrote: /dev/shm/gcc/rpmbuild/RPMS/x86_64/sssd-libwbclient-devel-1.13.90-0.fc23.x86_64.rpm
Wrote: /dev/shm/gcc/rpmbuild/RPMS/x86_64/sssd-debuginfo-1.13.90-0.fc23.x86_64.rpm
Executing(%clean): /bin/sh -e /var/tmp/rpm-tmp.jeWpr7
+ umask 022
+ cd /dev/shm/gcc/rpmbuild/BUILD
+ cd sssd-1.13.90
+ rm -rf /dev/shm/gcc/rpmbuild/BUILDROOT/sssd-1.13.90-0.fc23.x86_64
+ exit 0
To install SSSD on other distributions, you can run the usual Autotools combo:
autoreconf -i -f && \
./configure --enable-nsslibdir=/lib64 --enable-pammoddir=/lib64/security && \
make
sudo make install
To build and install the code. Please note that by default, the
Autotools install prefix is /usr/local. Also, if you are building
and installing on a 32bit machine, you should use /lib/ instead of
/lib64 for nsslibdir and pammoddir. Please note that even if
you are installing to /usr/local, the NSS and PAM libraries must be
installed to system library directories as that’s where NSS and PAM
would be looking for them.
Sending patch to upstream¶
Coding Style¶
We have adopted the code style and formatting specification used by the FreeIPA project to describe our Python coding style. For C language we also used FreeIPA C style but this style is currently outdated and a new updated C style guide was written for SSSD.
Spell-checker¶
Please, check the spelling before submitting.
Use your favorite spell-checker. Checking with LibreOffice can be done like:
- open file(s) that contain(s) changes with “LibreOffice Writer”
- set the document language to “English (USA)” (either Tools – Language – For all Text or select whole text with keyboard shortcut Ctrl+A, then click at the bottom in the middle)
- to start the check press F7 (equals Tools – Spelling and Grammar …)
- press [Ignore Once] for spelling mistakes press [Ignore All] to ignore the known good string until LibreOffice is closed press [Add to Dictionary] to add the word to the known good list
- fix spelling mistake with editor, not LibreOffice
- in terminal run fgrep -ri ${BADWORD} or egrep -r ‘REGEXP’ to double-check and find other instances of problem
Submitting¶
Please, read the basic etiquette paragraph of the GitHub workflow before submitting.
Make your changes and then add any new or modified files to a change-set with the command:
git add <path_to_file1> <path_to_file2> ...
git commit
Before submitting a patch, always make sure it doesn’t break SSSD tests and applies to the latest upstream master branch. You will want to rebase to this branch and fix any merge conflicts (in case someone else changed the same code).
git remote update
git rebase -i origin/master
If this rebase has a merge conflict, you will need to resolve the conflict before you continue. If you get stuck or make a mistake, you can use
git rebase --abort
This will put you right back where you started.
Patches should be split so that every logical change in the large
patchset is contained in its own patch. An example of this is SSSD
Ticket #2789 where one
patch makes the resolv_is_address() function public with tests and the
other adds the function in the SSSD providers.
Once your changes are ready for submission, submit it via a pull request.
If a patch isn’t accepted on the first review, you will need to modify it and resubmit it. When this happens, you will want to amend your changes to the existing patch with
git add <files>
git commit --amend
If you need to make changes to earlier patches in your tree, you can use
git rebase -i origin/master
and follow the directions in the interactive rebase to modify specific patches.
Then just re-push the patches, the pull request will be refreshed automatically.
Patch metadata¶
The description associated with the patch is an important piece of information that allows other developers or users to see what the change was about, what bug did the commit fix or what feature did the commit implement. To structure the information many SSSD developers use the following format:
- one-line short description
- blank line
- ticket or bugzilla URL (if available)
- blank line
- One or more paragraphs that describe the change if it can’t be described fully in the one-line description
These best practices are loosely based on the kernel patch submission recommendation.
An example of a patch formatted according to the above guidelines is commit 925a14d50edf0e3b800ce659b10b771ae1cde293:
LDAP: Fix nesting level comparison
Correct an issue with nesting level comparison of option
ldap_group_nesting_level to ensure that setting nesting level 0
will avoid parent group of group searches.
Resolves:
https://pagure.io/SSSD/sssd/issue/3425
Testing SSSD¶
There is a dedicated page about Running and developing SSSD tests.