Support

From Gentoo Wiki
Jump to:navigation Jump to:search

The Gentoo community volunteers will usually be happy to provide support for technical issues encountered when installing or using Gentoo Linux. Both Gentoo developers, and experienced users - from the talented community that builds, packages, tests, and documents the Gentoo Linux distribution - provide support in the various Gentoo communication channels, such as Forums, IRC, mailing lists, etc.

Before reaching out for assistance, please check if the issue at hand is already covered in the documentation, or elsewhere, such as in the the different venues available for getting assistance.

Tip
The Handbook, the documentation wiki, and the FAQ are the first places to look for preexisting solutions. Man pages and info pages are usually where the canonical documentation lives, or it may be online. Also consider that a solution may have already been discussed on the forums or mailing lists, or may be found elsewhere on the Internet with a search engine.
Important
Read the code of conduct before initiating communication in the official fora.

Please act in the spirit of collaboration and be courteous in the Gentoo fora, and abide by the code of conduct to help everyone get along in a professional environment. Supply any requested information, follow the guidance in this article, and hopefully a solution can be found!

Pay particular attention to the "how to formulate requests" section, and try to focus on the root problem when requesting support. Be concise and precise in order to best channel everything towards an efficient solution.

It is essential to let anyone helping with an issue know what worked and what didn't, at the place where the issue was discussed. Not doing so may even be considered impolite. It is also very useful to help the community by making an addition to the wiki, explaining how things were solved, for anyone who runs into the same problem! The wiki is very easy to edit by anyone, and it is very quick to get started.

Remember that Gentoo support fora are exclusively for Gentoo Linux matters. For software usage concerns, even for packages installed from the Gentoo ebuild repository, any support issues should be directed upstream. Gentoo support covers almost exclusively things maintained as Gentoo projects, and Gentoo-specific integrations.

Note
When asking for support, particularly on the #gentoo IRC channel, it will often be required to have correctly followed the Handbook, before any assistance will be provided. The Handbook is the official installation method for Gentoo, and it is generally not advisable to go against it, though it does provide much flexibility in itself. If warnings in the handbook are not followed, or if an installation deviates too much, it will probably be required to reinstall in order to get support.

First, check if a preexisting solution exists

It is usually easier to follow a preexisting solution than to ask for help. Gentoo has a relatively large user base, so there is a chance that someone has already encountered any given problem, and perhaps published a solution.

See also
It might be useful to refer to the troubleshooting page for tips on tracking down and solving issues oneself, before or after looking for a solution ;).

The people who volunteer support for Gentoo Linux give their time generously to help out. The first thing a user can do to give a little back is to track down any preexisting solution, so as to leave the volunteers more time to find fixes for new issues.

There are several important places that can provide such solutions:

Documentation

The Gentoo wiki contains the main documentation for Gentoo Linux, and it strives to be clear, complete, and of high quality. Documenting Gentoo is a huge effort, so there are still things to add, but the wiki remains the best reference for all things Gentoo! Be aware that occasionally, less maintained articles can sometimes contain errors or outdated information - but reading wiki articles is always important when using Gentoo.

Tip
The wiki search function can be very useful, and using an external search engine can be a good compliment to this.

The FAQ contains answers to many commonly encountered issues. See the Knowledge Base, for common practices and problems.

Man pages and the Info system are the primary source of information for many Gentoo tools and utilities, and should usually be the first place to look when having trouble using a particular command. Many commands also support the --help or -h switches.

The /usr/share/doc/ directory contains documentation files for many packages.

Note
If a package external to Gentoo is involved, any upstream documentation may be useful. Each project provides documentation in it's own way, but looking up the website and VCS for a package on https://packages.gentoo.org, or on the wiki, is a good place to start.

Bugs

The Gentoo bug tracking system contains information on many issues, and it is always possible that any problem encountered may have already been reported. Even past issues that have been marked as solved can still crop up in some situations.

Search for bugs that may be of interest with the bugs.gentoo.org search form. Upstream issue trackers may also hold important information.

Forums

There are many discussions on the Gentoo Forums covering resolving Gentoo Linux related issues. Take a look through the posts, use the integrated search functionality, or an external search engine, to locate any promising information.

Email notifications can be set up to inform of replies to posts.

Mailing lists

The Gentoo mailing lists can contain invaluable information.

Web search

The World Wide Web is a trove of information, and though many things may not always be accurate - to say the least - technical information abounds, and Gentoo in no exception. Open up search engine of choice and employ the tried and tested methods of locating information on the web.

Formulate requests properly

To get the best assistance possible, please state the issue at hand clearly. Provide necessary context, and include any information that will be useful to understand the situation.

Supply details when asked, because people often ask specific questions with a clear diagnostic hierarchy in mind.

When requesting help, the same wasteful pattern of asking for advice concerning the wrong issue comes up time and time again - so much so that someone came up with a name: the XY problem. This problem arises when people start out on an attempt at a solution, but when this fails, they ask about the issue with that solution, rather than asking about the problem they were having in the first place.

Tip
Ask about the root problem, not about problems encountered when trying to implement a specific solution. If the root problem is laid out, it will open the conversation to all available fixes. Starting off centering on issues met when working on just one particular solution will close many avenues to resolution.

If some solutions have been ruled out, or tried and failed, mentioning this can provide more awareness of the situation.

Fora to ask for assistance if no preexisting solution can be found

Gentoo provides several venues to request assistance, and the one to use can vary depending on the nature of the problem, and preference.

Note
Be prepared that the reply to some questions may be that an issue is not in the purview of Gentoo support. Some issues should be referred upstream. The developers may even have their reasons to decide that some concerns with Gentoo are best not to be "fixed", or that it would take too much effort to change something that can be worked around, when time would be better spent elsewhere.
Tip
Refer to the collecting additional information section of the troubleshooting article for tips on how to provide certain information along with support requests.

Forums

The Gentoo Forums provide support for the Gentoo user community, amongst other things. Users may post support questions to be answered by developers, or other knowledgeable users. See the forum project page for the forum's presence on this wiki.

IRC

Internet Relay Chat is a reliable instant messaging protocol. Gentoo manages several channels for support on Libera Chat, to allow dynamic exchange between all members of the community. See the IRC article for details of how to use IRC to get support for Gentoo.

The support channel is #gentoo (webchat), and is available as a "webchat" in the browser via the preceding link. IRC is probably the fastest way to get an answer, but some times are quieter than others, and some channels are low traffic. Stick around in a channel and wait for a reply, and if things are really taking a while, set an alert for channel activity ;).

Tip
Please do not paste long text excerpts, or whole files, to IRC. Use wgetpaste if long passages are to be shared.

Mailing lists

The Gentoo mailing lists can be a useful venue to ask for support.

Contribute solutions back

A great way to move Gentoo forward is to contribute solutions back by making an addition to the wiki. Once a solution that could be of use to others is identified, it should be trivial to write it up on the appropriate place in the wiki: it really isn't hard to make an edit, small changes can take seconds and are as simple as editing any text file.

Gentoo exists because people have come together to build an OS, using what they believe to be best practices. Every contribution made in the spirit of collaboration will help make Gentoo a bit better. Even a small contribution has value, and everyone will be thankful. All great things start with the first step, and experienced users will be happy to assist anyone making additions.

To make a small correction for the first time, the quick start guide gives a short overview of the essentials.

Tip
There are troubleshooting sections at the end of many wiki articles, which can be a great place to add new solutions to any issues that could possibly occur for others.
Important
If an actual issue is found that would merit being looked into by the developers, filing a bug is an essential contribution.

Remember that there are other ways to contribute to Gentoo.

When all else fails - report a bug

If it appears that something is broken with Gentoo, please file a bug on Gentoo's bug tracker. This is a very effective way to reach the Gentoo Developers, who can then use the feedback to improve the situation.

There are a couple of guides for reporting bugs on the wiki: Bugzilla/Bug report guide and Bugzilla/Guide.

See also

External resources