Frequently asked questions

Getting started with an issue tracker

Open source software projects typically allow users to interact directly with the communities that create and maintain the software they use every day. This is especially beneficial when users have questions, need help, or have suggestions for improving the software.

Open source software communities manage error reports and feature requests via tools called "issue trackers." Anyone seeking to interact with an open source software project should understand how to use an issue tracker.

Question: What is an issue Answer: An issue tracker (sometimes called a "bug tracker,” "issues list," or "issue queue") is a tool for submitting reports that open source software communities can use to improve the software they create. tracker? You might file a report (or "open an issue") when software does not function as you expect it to. You might also file an issue to make note of a potential security vulnerability in a piece of software, report inaccurate documentation, or suggest new software features.

Many platforms used for collaborating on open source software projects—like GitLab and GitHub—feature issue trackers. Other commonly used issue trackers include , , and Trac.

Answer: Software projects use issue trackers to coordinate development and establish project roadmaps. Question: Why do open source A project's issue tracker often functions as that project's to-do list. Issue trackers help project projects use issue trackers? communities monitor pending tasks, set priorities, comment on potential solutions, and collaboratively review work-in-progress. Additionally, because it can be challenging for project contributors to keep track of all conversations occurring across a project's communication platforms, the project's issue tracker is a reference point for synchronizing work. Real-time chat and social media are ephemeral but the issue tracker is purpose-built for recording and reviewing software problems, which is why most communities prefer it for these purposes.

Question: Why should I use an Answer: Filing an issue may seem more cumbersome than asking for help in real-time chat but doing it is open source project's issue important for several reasons. tracker? • Gaining visibility: By reporting issues using a project's issue tracker, you help project maintainers become aware of issues in open source software. Ensuring a problem is logged in an issue tracker increases the likelihood that developers will address it. • Creating a record: Filing an issue allows the issue reporter and project contributors to communicate about the problem effectively and asynchronously. Everyone working to address an issue can leave comments, pose questions, and propose fixes at any time. • Grouping issues: When you find a problem with the software, you might discover that the problem is also causing another problem, or there may be several problems that are related. Issue tracking allows project developers to group related issues together, which may aid in diagnosing a problem's root cause. • Streamlining organization: People often encounter the same potential problems with software and file similar issues. Issue trackers allow project maintainers to link reports together, avoid duplicating work, and streamline communication about common bugs. Frequently asked questions

Question: What should I include Answer: An issue report should include any information that may be useful for diagnosing a problem. Be in an issue report? as detailed and specific as possible. Many projects provide issue templates that guide you in submitting your report, outlining the minimum information the project maintainers need to understand the problem. If

a project does not offer such a template, be sure to include:

• Basic details about the software you are using, such as the version number and the platform on which it is running. • A summary of the issue. • Steps to reproduce the problem. A description of behavior you observe. • • A description of the behavior that should be occurring instead.

Some projects may request that you attach files—such as a log file or screenshot—to the report. Some

issue trackers allow you to add labels (or "tags") to an issue. Most communities prefer that you do not do so without consulting project maintainers. Because maintainers use these labels to organize, prioritize, and filter issues, they often prefer to add and manage the labels themselves. Cleaning up misleading,

inaccurately labeled issues can be time consuming. Trust that maintainers reviewing your error report will label them appropriately.

Answer: Remember that many open source software projects are maintained by volunteer contributors Question: How long should I wait who work on the project in their spare time. Set your expectations accordingly. Response delays of a week to receive a response from someone when using a project's or more are not unreasonable. If your issue is urgent, consider discussing it in other channels after you filed issue tracker? the report and asking if anyone is available to help. If your request in the issue tracker goes unanswered, wait at least 48 hours before repeating it on a project mailing list, real-time chat, or social media. For

commercially supported open source software, you should expect a response time as promised in your support contract.

Answer: When communicating with open source communities—on issue trackers or anywhere else—clarity Question: What else should I and kindness are key. Most communities understand that people become frustrated when the tools they know about communicating with are using do not work as intended. Likewise, someone developing those tools—often as a hobby—is unlikely communities using issue trackers? to respond well to demands that they devote time to fixing issues that they may not have encountered. Be gracious in your discussions with project participants because everyone sharing their knowledge is contributing to the project's overall health. Thank the people creating the software for their time and energy, especially if you have not filed issues previously.

North America 1 888 REDHAT1 www.redhat.com

Europe, Middle East, and Africa 00800 7334 2835 [email protected] About Red Hat Asia Pacific +65 6490 4200 Red Hat is the world’s leading provider of enterprise open source software solutions, using a community- [email protected] powered approach to deliver reliable and high performing , hybrid cloud, container, and Kubernetes Latin America technologies. Red Hat helps customers integrate new and existing IT applications, develop +54 11 4329 7300 cloud-native applications, standardize on our industry leading , and automate, secure, [email protected] and manage complex environments. Award winning support, training, and consulting services make Red Hat a trusted adviser to the Fortune 500. As a strategic partner to cloud providers, system integrators, application vendors, customers, and open source communities, Red Hat can help organizations prepare for facebook.com/redhatinc the digital future. @Redhat linkedin.com/company/red-hat Copyright © 2021 Red Hat, Inc. Licensed under the Creative Commons Attribution-ShareAlike 4.0 International License. Red Hat and the Red Hat logo are trademarks or registered trademarks of Red Hat, Inc. or its subsidiaries in the United States and other countries. Linux® is the registered O-F24816 trademark of Linus Torvalds in the U.S. and other countries.