#18 Add user-facing documentation howto on filing bug reports
Merged 6 years ago by mzidek. Opened 6 years ago by jhrozek.
SSSD/ jhrozek/docs master  into  master

file modified
+1
@@ -7,4 +7,5 @@ 

  .. toctree::

     :maxdepth: 1

  

+    reporting_bugs

     releases

@@ -0,0 +1,136 @@ 

+ .. highlight:: none

+ 

+ How to file a useful SSSD bug report

+ ====================================

+ 

+ Unfortunately, SSSD is not perfect and sometimes, you might encounter a

+ bug. This document describes how to file an SSSD bug report or an enhancement

+ request. Providing accurate and well formed information might help us find

+ the bug and ultimately fix it. As a bug reporter, you should work with us

+ on pinpointing the bug - we should then work with you on fixing the bug.

+ 

+ Where to file the bugs?

+ -----------------------

+ 

+ You'll need a `Fedora Account System <https://admin.fedoraproject.org/accounts>`_

+ login to file a bug. When you have one, navigate to

+ `the new ticket form <https://pagure.io/SSSD/sssd/new_issue>`_

+ 

+ Some bugs will be automatically cloned from distribution bug-trackers,

+ such as http://bugzilla.redhat.com.

+ 

+ Help us reproduce the bug

+ -------------------------

+ 

+ The easier for us is to see the flaw in our environment, the easier it is

+ to fix the bug. If we can't conclusively see the bug exist, it might even

+ be closed as invalid. If the bug can't be reproduced easily, describe your

+ environment in detail and allow us more time to analyze your problem.

+ 

+ Include necessary debugging data

+ --------------------------------

+ 

+ Always include the following data in a bug report:

+ 

+     * One bug report per ticket. If you think you found multiple problems,

+       file each one in a separate ticket

+     * Search the ticket database for possible duplicates. If you find

+       a duplicate, please add a comment saying that you encountered the

+       problem as well.

+     * Is this a defect or an enhancement?  If the ticket you are filing

+       is about adding new functionality and not about a defect in existing

+       functionality, please add the ``RFE`` tag.

+     * Short summary. A good example is: "The LDAP provider segfaults when

+       an invalid TLS certificate is specified".

+     * CC (optional). If there are other parties interested in a particular

+       bug, please ``@mention`` their Fedora usernames in the ticket.

+     * What platform are you on? Please provide the operating system version

+       and architecture.

+     * The SSSD version. On an RPM-based system, you can just run ``rpm -q

+       sssd``. (If the bug is in the current working tree, please mention

+       that as well)

+     * The SSSD config file. Typically this would be located at

+       ``/etc/sssd/sssd.conf``

+     * The SSSD log files with a high debug level. Please see the

+       troubleshooting page on information on how to gather them and other

+       required information. When submitting the logs, it's very helpful

+       to remove the existing log files before running the test case. This

+       ensures the logs only capture the problem and developers don't need

+       to weed out gigabytes of info.

+     * The steps to reproduce the bug. It's very useful to log the times of

+       the commands that reproduce the bug as you execute them. For instance,

+       if two ``id`` commands run in sequence would give different information

+       for the admin user, please run them like this::

+ 

+         $ date; id admin; date; id admin; date

+ 

+       This would help us cross-link your actions with the log files.

+     * Describe your network topology and the server types and versions. This

+       is especially important in complex setups with trusted IPA or Active

+       Directory domains.

+     * What are the results you expect? What were the results you see

+       instead? Please be specific. A bad example is "My logins are slow". A

+       much better example is "When a user who is a member of 100 groups logs

+       in, his login takes 50 seconds even though a kinit and id -G for the

+       same user are fast."

+ 

+ Some data in the SSSD tickets are handled by the SSSD team members. Please

+ leave Priority, Milestone, and Assignee to their defaults.

+ 

+ Providing SSSD crash data

+ -------------------------

+ 

+ In addition to the data described above, please also provide the coredump

+ and backtrace along with the bug report.

+ 

+ If you are on a Fedora or RHEL system, ``abrt`` is a great tool for

+ gathering crash info. If abrt is not available, you can retrieve the

+ core file and backtrace manually. First, find out which sssd process is

+ crashing. Please always make sure you have the exact matching debuginfo

+ package version on your system. On Fedora and RHEL, you can easily install

+ the debuginfo packages with ``debuginfo-install sssd``. Then, connect to

+ the faulty process with gdb and resume it::

+ 

+     # gdb program $(pidof sssd_be)

+     (gdb) continue

+ 

+ When the program crashes, save the core file and backtrace::

+ 

+     (gdb) generate-core-file

+     Saved corefile core.7336

+     (gdb) bt full

+     # lots of output, copy and paste to the bug report

+ 

+ Then attach the core file and the backtrace.

+ 

+ Mind your privacy

+ -----------------

+ 

+ Both the SSSD log files and the coredumps might include confidential

+ information. If you don't like them to be exposed in the SSSD bug tracker

+ instance, please contact some of the SSSD developers on the ``#sssd``

+ channel on FreeNode or on the

+ `sssd-users <https://lists.fedorahosted.org/archives/list/sssd-users@lists.fedorahosted.org/>`_

+ mailing list.  

+ 

+ Always test the latest available version

+ ----------------------------------------

+ 

+ SSSD moves at a rapid pace. It's not useful to file a bug report against

+ an old version, please upgrade to the latest release in the branch you're

+ running, if the branch is still active. You can find the tarballs on our

+ releases page. If you're running an Enterprise or Long-Term-Maintenance

+ distribution and can't update to a newer version, consider filing a bug

+ report in your distribution bug tracker instead.

+ 

+ Alternatively, ask on the ``#sssd`` channel on FreeNode. Several SSSD or

+ FreeIPA developers maintain private repositories with custom builds for

+ stable platforms.

+ 

+ Consider if the bug has security consequences

+ ---------------------------------------------

+ 

+ If you think you found a bug that has security impact (allows an unprivileged

+ user to take down SSSD or elevate privileges for instance), don't file the

+ bug in a public bug tracker. Instead, e-mail any of the SSSD developers

+ instead.

There are some minor content changes except for the s/fedorahosted/pagure/ changes. I removed the mention of selecting a component because we don't really use that anymore and asked to add RFE tag instead of ticket type.

ACK! Please, feel free to merge it.

Pull-Request has been merged by mzidek

6 years ago
Metadata