en-us/about_dbatools_support.help.txt

TOPIC
    about_dbatools_support

SHORT DESCRIPTION
    Describes how to contact support and what information we need

LONG DESCRIPTION
    Welcome to the dbatools support guide.
    If you are reading this, odds are, something went wrong and you are looking
    for support. Sorry for the inconvenience - we try our best to have dbatools
    as free of bugs as we can manage. Doesn't always work out.

    This article describes how you can reach us and what information we need
    when you do.


    #-------------------------------------------------------------------------#
    # Table of Contents #
    #-------------------------------------------------------------------------#

    - Getting Help
    - Troubleshooting Support
    - A matter of timing
    - What happens now?
    - The world need not burn


    #-------------------------------------------------------------------------#
    # Getting Help #
    #-------------------------------------------------------------------------#

    When something breaks unexpectedly, you'll probably want help. Well, most of
    us in the team work on dbatools, because we a) have fun coding and b) like
    the community (there is no pay involved whatsoever). So, come see us in our
    Slack channel or file an issue on github. We will gladly attempt to help you
    with any technical issues using our module (we love our module, we'll remove
    any malfunctioning blemishes that we can!).

    In order to find us, you can visit us on Slack by following this link:
    https://dbatools.io/slack/
    This has the advantage of the easiest interaction and often the fastest
    resolution times for smaller issues.

    Alternatively, you can file an issue on github:
    https://github.com/dataplat/dbatools/issues
    (Don't worry: It's relatively straightforward and easy to do)

    When you describe an error, please be prepared to provide some information,
    such as what code you were trying to execute and what the error was. For
    more details on this, see the next chapter: "Troubleshooting Support"


    #-------------------------------------------------------------------------#
    # Troubleshooting Support #
    #-------------------------------------------------------------------------#

    When trying to figure out, what went wrong, we usually need information,
    quite a bit of it, in fact. Usual information we care about:
    - Code/line you were running
    - Output / Error / Warning received
    - Exception contents
    - Execution log
    - PowerShell Version
    - Operating System
    Now, we rarely need all of that, but often we don't know what of it we need
    before looking at it in more detail. That said, I highly recommend providing
    the first three points immediately, as they are fast to gather and already
    help a lot. We may ask for more as it comes up.

    # Code/line you were running #
    #----------------------------#

    Literally the code you executed. Make it as simple as possible and still
    produce the error. Make sure to replace sensitive data before posting it.
    If you can reduce it to a single line, that's great! (But don't sweat it if
    it's still more)

    # Output / Error / Warning received #
    #-----------------------------------#

    Generally, we catch errors and write warnings by default. Report what it
    wrote if that is the case. Same for red exception textes. Sometimes however,
    a command may just refuse to do anything at all. In that case it might just
    return nothing. If it doesn't write a warning or throw an exception, tell us
    what you expected it to do and what it did instead.
    Screenshots work very well for this.

    # Exception Contents #
    #--------------------#

    If the code threw an exception or wrote a warning, behind the scenes some
    code failed to work as designed. This failure information is usually the
    most valuable piece of information for troubleshooting. Generally, you can
    see that exception content by running the following line:

      $error[0] | Select-Object *

    Directly after the command failed. Screenshot it.

    # Execution Log #
    #---------------#

    Dbatools logs a lot of information about how a function processes its logic.
    You can access that information by running Get-DbatoolsLog. In order to
    send in this information, start a new process and produce the error, then
    execute the following line:

      Get-DbatoolsLog | Export-Csv messagelog.csv

    This will export the entire log into a csv file. You may want to edit out
    confidential information (replace it with something harmles) before
    submitting it.

    # PowerShell Version #
    #--------------------#

    We try to support versions 3-5.1 of PowerShell. Sometimes however we mess up
    and something doesn't work on all versions. Thus the actual PowerShell
    version is often of interest. You can find this information by running the
    following line:

      $PSVersionTable

    # Operating System #
    #------------------#

    What version of Windows are you running your code on?

    # Ugh, this is a bit much, can't you just gather what you need yourself?! #
    #-------------------------------------------------------------------------#

    Yes, we can! We've got a command that gathers all the data that it can and
    bundles it in a zip file for submission. Beware though: It is seriously hard
    to hide or redact data from it, as it gathers a lot and stores it in an XML
    file that must be edited from PowerShell, if at all. If you don't
    particularly worry about sharing the data though, simply run this command:

      New-DbatoolsSupportPackage

    It'll handle the gathering. Just submit the resultant zip file and we have
    all the information your console has to give.


    #-------------------------------------------------------------------------#
    # A matter of timing #
    #-------------------------------------------------------------------------#

    When gathering information for an error, we highly recommend taking the
    following steps:

    - Start a new PowerShell console
    - Perform the action necessary to reproduce the error
    - Gather data

    This has two key benefits:
    - The least amount of data gets collected, meaning we have to search through
      less material to find the cause.
    - Reduces the likelyhood of accidentally sharing confidential data


    #-------------------------------------------------------------------------#
    # What happens now? #
    #-------------------------------------------------------------------------#

    Alright, you've gathered the data needed and told us about the issue? Good.
    What happens next usually depends on what kind of issue it is and where you
    went to report it:

    Reported on Slack
    - Minor bug: When you report what turns out to be a minor bug (minor
      refering to the technical complexity of the issue, not your problem that
      lead you to us), especially on the slack channels, odds are, on of us
      picked it up and immediately resolved it. In this case we'll tell you
      "it's handled" and that's it as far as you go: In the next release, the
      issue will be gone.
    - Major issue: Some bugs are just too technically complex to solve on the
      fly. In those cases we will ask you to file an issue or file it for you,
      whichever you prefer. We'll try to see it resolved in a timely manner and
      inform you as it has been resolved or ask you to try out a current build
      and confirm it.

    Reported on GitHub
    The key differences between reporting a problem on Github and doing so on
    Slack is that are:

    a) We cannot ask questions directly as you post.
    b) Reporting the issue does not require team members to be present.

    We often ARE there, hanging out in Slack, but it is not automatically
    guaranteed. That being said, after you have filed an issue on GitHub, please
    keep track of that issue, as we will likely ask questions or ask you to test
    out solutions. Really, the process is mostly the same, only that since we
    can't make sure all the information we need is there when you report it, we
    may need to ask for it.


    #-------------------------------------------------------------------------#
    # The world need not burn #
    #-------------------------------------------------------------------------#

    Thank you for reading our advisory on receiving support. Note however: It is
    totally not necessary to wait until something breaks to contact us: Come on
    over into the slack channels and hang out, discuss sql server or the
    benefits of the local breweries.


KEYWORDS
    dbatools general support help