There are three primary places where the Salt community gets together to discuss the software and help each other out: the mailing list, the IRC chat room, and the issue tracker on GitHub.
There are three types of messages that you will generally find in these places: questions about the software, bug reports, and feature requests. In general, questions about the software should be asked either on the mailing list or in IRC. Bug reports and feature requests are better suited to the issue tracker.
The salt-users mailing list is a very active discussion environment, hosted on Google Groups. The mailing list can be found at:
https://groups.google.com/d/forum/salt-users
You can browse the mailing list at the preceding link, or you can set up an e-mail subscription and get messages sent to your inbox, where you can reply to them. There are, typically, a good dozen or so e-mails a day, so if that sounds like too many, then maybe just looking online is the way to go.
If you're going to post a question, there are a few guidelines that will help you out:
When you ask a question, try to post enough information about your problem so that people will be able help you out. In the past, people have asked how to fix a particular problem without stating what the problem actually is, or in some cases, even the part of Salt that the question pertains to. As you can imagine, this isn't helpful to anybody.
Describe what you're trying to do, and what you expect to happen. If something isn't working the way that you expect, make sure to state what is actually happening.
You may need to post the output from a command in order to explain what is happening. If this is the case, make sure to post the actual command that you're running, and the relevant part of the output. If you issue a command that results in dozens of lines of logging output, but the actual error only takes up five lines, then just post those five lines to start with. If somebody asks for more, then go ahead and post more.
Tip
Be careful when posting logs and configuration files! All too often, people will accidentally post an API key, password, or private network information without meaning to. Before pasting any information at a place online, where somebody can see it, make sure to remove any sensitive information. Making sure not to post long log messages will make this a lot easier.
It is also helpful to know which version of Salt you are running. It is likely that your particular experience is unique to a specific version of Salt. Rather than just saying which version of Salt, it is often more helpful to give the output of the following command:
# salt --versions-reportIf you are working with Salt Cloud, then make sure to get that report instead, using:
# salt-cloud --versions-reportBecause Salt Cloud uses a different set of libraries, using its
versionsreport will give more information that may be useful, in addition to all of the version information for Salt itself.If you happen to find the resolution for your situation from outside the mailing list, it is also a good idea to reply to your own thread with a copy of the solution. The mailing list is archived on Google's servers, and if somebody else with your issue searches for it, they will appreciate seeing the solution. Believe me, few things are more frustrating than finding a dozen different people asking the same question on a dozen different mailing lists, with either no solution or a message from the original person saying, "Hey, I figured it out," and leaving it at that.
IRC, or Internet relay chat, is a type of chat room that's been around for a very long time. If you already have an IRC client, you can connect to the Freenode server at:
And then join the Salt chat room at:
#salt
If you don't have an IRC client yet, you might want to consider Pidgin, which is a chat client that supports a number of chat protocols. It's not the most popular IRC client by any means, but it's easy to use and available for Windows, Mac, and Linux. You can download it at:
If you don't want to commit to an IRC client, Freenode does have a web-based IRC client that you can use to connect to Salt's chat room. You can find this client at:
When you connect to Salt's chat room, there are a few things that will be useful to know:
Be patient. There are hundreds of people logged in to the Salt chat room at any given time, but not all of them are actively participating. It is very common for people to log in to an IRC room while at work, and check it periodically throughout the day. When you ask a question, don't expect an immediate answer. Somebody may be watching at that moment and try to help you, but it may take an hour for the right person to see your question and jump in to try to answer it.
Be ready to provide information as necessary. The kind person who offers to help you may ask for log messages or code snippets, or may ask you to try a few different commands, and post the response.
You may want to look into getting an account on a text-sharing service. One such popular service is PasteBin:
However, you might also want to look into using GitHub's gist service:
This has become an increasingly popular way to share logs and code snippets as with PasteBin, but with the kind of revision management that Git is known for.
Post solutions. As with the mailing list, conversations in the Salt chat room are archived. You can find them at:
https://irclog.perlgeek.de/salt/
If you find the solution as you are working on the problem, and it's not obvious by looking at the conversation what it is, make sure to post it in the chat room so that others can find it later.
When you come across a situation that you know is a bug, or you have a feature request, the Salt issue tracker on GitHub is the way to go. You can find it at:
https://github.com/saltstack/salt/issues
You may come across a situation where you don't know whether your problem is the result of inexperience, or an actual bug. If you're not sure, go ahead and post it on the mailing list. If it is a bug, then you will probably be asked to file an issue in the issue tracker, assuming somebody else hasn't already filed the same issue.
One of the advantages of filing an issue in the issue tracker is that you are automatically subscribed to updates for that issue. That means that when others post questions and comments on the issue, you will receive an e-mail with a copy of their response. If somebody else posted the issue, then you can still subscribe to it. Just look for the Subscribe button on the right-hand side of the issue page:
Once you hit that button, it will change to say Unsubscribe. If you ever get tired of receiving updates for that issue (even if you created it), then you can unsubscribe from it. But if you've left comments, I would encourage you to remain subscribed, in case anybody wants to ask you further questions down the road.
Once again, make sure to post any relevant information, exactly as you would on the mailing list. Detailed information about the issue, version reports, and code snippets are all helpful. A very recent addition to the Salt issue tracker is the use of templates, which provide reminders as to which information to give.
One incredibly helpful feature in GitHub is the ability to use markdown. You can find a helpful guide to markdown at:
https://guides.github.com/features/mastering-markdown/
By far the most useful markdown syntax to know is how to mark out code blocks. The character used to mark out code is commonly known as the backtick, also known as the grave accent. On an American QWERTY keyboard, this key is located in the top-left position:
When you place a single backtick in front of a piece of text and another at the end, then the text will be formatted as a piece of code. If you need to format multiple lines, then start with three backticks together on the first line, and three more together on the last line. Blocking out code this way helps immensely with readability.
