Metadata-Version: 2.1
Name: sopel_modules.github
Version: 0.4.5
Summary: GitHub plugin for Sopel
Home-page: https://github.com/sopel-irc/sopel-github
Author: Max Gurela
Author-email: maxpowa@outlook.com
Maintainer: dgw
Maintainer-email: dgw@technobabbl.es
License: Eiffel Forum License, version 2
Description: # Sopel GitHub
        
        GitHub plugin for [Sopel](https://sopel.chat/) IRC bots.
        
        
        ## Installation
        
        The easy (and recommended) way: `pip install sopel_modules.github`
        
        The less-easy way; you must already have Sopel installed to use this method.
        ```
        git clone https://github.com/sopel-irc/sopel-github
        cd sopel-github
        pip install .
        ```
        
        ## Out-of-the-box Functionality
        
        Detects when GitHub URLs are posted and takes over URL handling of them, pretty
        printing details of:
        
         * Commits
         * Issues
         * Issue Comments
         * Pull Requests
         * Pull Request Comments
         * Repositories
        
        Also pretty prints repository details on command, using either `.gh user/repo`
        or `.github user/repo`. If you omit the user, it will assume your IRC nick is
        the user. For example:
        
        ```
        <@maxpowa> .gh sopel-github
        <Sopel> [GitHub] maxpowa/sopel-github - GitHub module for Sopel | 100.0% Python
                | Last Push: 2015-10-16 - 04:00:32UTC | Stargazers: 0 | Watchers: 0 |
                Forks: 0 | Network: 8 | Open Issues: 0 |
                https://github.com/maxpowa/sopel-github
        
        <+salty> .gh sopel-irc/sopel-github
        <Sopel> [GitHub] sopel-irc/sopel-github - GitHub module for Sopel | 100.0%
                Python | Last Push: Sunday, May 12, 2019 17:05:43 (CDT) | Stargazers: 3
                | Watchers: 1 | Forks: 8 | Network: 8 | Open Issues: 18 |
                https://github.com/sopel-irc/sopel-github
        ```
        
        If you have [the `emoji` package](https://pypi.org/project/emoji/) installed,
        most `:emoji_name:`s will be converted to Unicode emoji in the output. (GitHub
        supports some non-standard names that this plugin doesn't handle yet.)
        
        
        ### API Keys & Usage
        
        GitHub's API has some fairly lenient unauthorized request limits, but you may
        find yourself hitting them. In order to prevent yourself from hitting these
        limits (and potentially being blacklisted), you should generate GitHub API
        keys for yourself. Fill out the information at
        https://github.com/settings/applications/new and then populate your
        configuration with your newly generated client key and secret.
        
        __IF YOU PLAN ON USING WEBHOOK FUNCTIONALITY:__ You _must_ properly fill out
        the "Authorization callback URL" to match the external URL you plan to use for
        the webhook.
        
        
        ## Webhook Functionality
        
        Webhook functionality is __disabled__ by default. It requires slightly more
        technical knowledge and configuration may vary depending on your system.
        
        ### Configuring Webhooks
        
        There are two possible ways to set this up: behind a proxy or directly exposed
        to the web.
        
        #### Configuring behind a proxy
        
        This is the __recommended__ way of configuring the webhook functionality, as
        there may be security flaws in the other method.
        
        First, configure the GitHub module. You may do so by running `sopel
        --configure-modules` or changing the config file directly.
        
        ```
        [github]
        webhook = True
        webhook_host = 127.0.0.1
        webhook_port = 3333
        external_url = http://bad.code.brought.to.you.by.maxpowa.us/webhook
        ```
        
        The above configuration is only listening on `localhost (127.0.0.1)`, because
        I'm using a reverse proxy in nginx to proxy `/webhook` to port 3333. The
        reverse proxy configuration would be fairly simple, as shown below. `/auth`
        must be included to match the "Authorization callback URL" you set when
        generating the API keys.
        
        ```
        location ~ /(webhook|auth) {
            proxy_pass http://127.0.0.1:3333;
        }
        ```
        
        #### Configuring exposed to the web
        
        If you're not using a proxy, your config will look something like this:
        
        ```
        [github]
        webhook = True
        webhook_host = 0.0.0.0  # Or a specific interface
        webhook_port = 3333
        external_url = http://your.ip.here:3333/webhook
        ```
        
        ### Creating hooks
        
        As an OP+ in a channel, you may type `.gh-hook user/repo`. You will see some
        informational text on what you need to do to finalize the hook, including a
        link to click to authorize the creation of the webhook. You will be required
        to authorize the GitHub application to read/write your webhooks (see
        [L163-164](https://github.com/sopel-irc/sopel-github/blob/9afaf1e51d9c28a1bbba7b442f6e7dea7db74018/sopel_modules/github/webhook.py#L163-L164))
        but this should be the _only_ permissions we need.
        
        ```
        <@maxpowa> .gh-hook maxpowa/sopel-github
        <Sopel> Successfully enabled listening for maxpowa/sopel-github's events in
                #inumuta.
        <Sopel> Great! Please allow me to create my webhook by authorizing via this
                link: <git.io link>
        <Sopel> Once that webhook is successfully created, I'll post a message in here.
                Give me about a minute or so to set it up after you authorize. You can
                configure the colors that I use to display webhooks with .gh-hook-color
        ```
        
        After you've authorized the webhook creation, you will be redirected to a
        simple page informing you that the bot succeeded/failed creating your hook.
        Assuming it succeeded, you should see a generic message appear in the channel
        you activated it in.
        
        
        ### Customizing hooks
        
        You may customize the colors that each part of the hook takes on. After setting
        the new colors, Sopel will reply with a sample of the new colors, e.g.:
        ```
        <@maxpowa> .help gh-hook-color
        <Sopel> .gh-hook-color <repo> <repo color> <name color> <branch color> <tag color> <hash color> <url color>
        
        <@maxpowa> .gh-hook-color maxpowa/Inumuta 13 15 6 6 14 2
        <Sopel> [maxpowa/inumuta] Example name: maxpowa tag: tag commit: c0mm17 branch: master url: http://git.io/
        <@maxpowa> Unfortunately, IRC colors don't show up on GitHub.
        ```
        
        
        Changes in 0.4.5
        ================
        
        Fixed:
        * Link matching did not allow for underscore (`_`) in repo names (#100)
        
        
        Changes in 0.4.4
        ================
        
        Fixed:
        * Regression in handling inline/standalone issue references (#99)
        
        
        Changes in 0.4.3
        ================
        
        Changed:
        * Skip trying to handle non-repo links, e.g. to topics (#97)
        
        Fixed:
        * Issue comment handling tries to access state (#95)
        * Error in cases where issue/PR body is empty (#98)
        
        
        Changes in 0.4.2
        ================
        
        Added:
        * Include issue/PR state when fetching info (#87)
        
        Changed:
        * Link shortening failures will be logged for debugging (#88)
        
        
        Changes in 0.4.1
        ================
        
        Added:
        * Include link to issue/PR in output when triggered by bare numeric reference
          in chat (#85)
        
        Fixed:
        * Double space in output of "self-assigned" webhook events (#80)
        
        
        Changes in 0.4.0
        ================
        
        Added:
        * Optionally treat references like `#123` in chat as issue references,
          configurable per-channel with new `.gh-repo` command (#65)
        * Webhook handling for issue transfer events (#75)
        * Rudimentary handling for links to files (#76)
          * Will try to show a useful text snippet if link points to a line/range
        * Webhook handling for PR converted from Ready to Draft (#77)
        
        Changed:
        * PR output includes more details (#69)
          * Author's name added if merged PR was not created by the merging user
          * Repo owner's name added to refs if PR head branch is in a fork
        * Commit references in webhook output will be abbreviated in most cases (#78)
        * Include title in assignee, label, & milestone webhook output (#79)
        
        Fixed:
        * Skip label-related events that do not include the label object (#66)
          * Avoids channel spam when deleting a label, for example
        * Correct fallback behavior for `.gh` command with no argument (#68)
        * Avoid "Socket already in use" error when IRC reconnects (#72)
        
        
        Changes in 0.3.2
        ================
        
        Fixed:
        * Unhandled exception on linked issue/PR with empty description (#67)
        
        
        Changes in 0.3.1
        ================
        
        Fixed:
        * Use of deprecated method `bot.msg()` (#63)
        * Use of deprecated `bot.privileges` property (#64)
        
        
        Changes in 0.3.0
        ================
        
        Changed:
        * Require Sopel 7.x and use its features (#58, #61)
        * Ignore lines that look like (HTML) comments or headings when shortening
          comment bodies (#57)
        * Deprecated query string API authentication replaced by HTTP Basic Auth (#62)
        
        Fixed:
        * Handle missing user information in commit data (#59)
        
        
        Changes in 0.2.6
        ================
        
        Fixed:
        * Syntax error in webhook code
        
        
        Changes in 0.2.5
        ================
        
        Added:
        * Error handler in webhook authorization (#51)
        
        Fixed:
        * Wrong config value access in webhook authorization (#51)
        
        
        Changes in 0.2.4
        ================
        
        Fixed:
        * Comments with trailing whitespace incorrectly had `[…]` appended even if the
          body contained only one line of (non-quoted) text (#50)
        
        
        Changes in 0.2.3
        ================
        
        Changed:
        * Milestone name is now included in `demilestoned` webhook events (#46)
          * GitHub originally didn't include this information in the webhook payload,
            but started sending it in approximately late-summer 2019
        
        Fixed:
        * Comments that were not truncated would still have `[…]` appended if the
          comment body included quoted text (#47)
        
        
        Changes in 0.2.2
        ================
        
        Changed:
        * Comment bodies will be shortened to approx. 250 characters, to try and stay
          within the length limit of one IRC line (#45)
        
        Fixed:
        * Repo URLs can be detected even with leading text on the line (#44)
        
        
        Changes in 0.2.1
        ================
        
        Fixed:
        * Comments containing blank lines would cause errors (#43)
        
        
        Changes in 0.2.0
        ================
        
        Added:
        * Handling for several new event types:
          * Pull request reviews (#20)
          * Pull request assignments (#23)
          * Pull request labels (#23)
          * Pull request milestones (#35)
          * Issue & pull request title edits (#36)
          * Releases (#21)
        * Handling of draft pull requests (#34)
        * Handling for draft pull requests marked ready for review (#34)
        * Converting `:emoji:` to Unicode emoji in most text output (#17)
          * Requires optional dependency: https://pypi.org/project/emoji/
        
        Changed:
        * `secret` setting is now called `client_secret` (#42)
          * The plugin will automatically migrate configs to use the new name, but
            manual editing is encouraged in advanced setups (e.g. if the user Sopel
            runs as cannot write to the config file)
        * Quoted text is ignored when generating comment output (#41)
        * Unicode ellipsis now used instead of three periods (#31)
        * Oxford comma now used in generated lists (#40)
        * Webhook payload processing is handed off to a separate thread (#22)
          * Bottle can handle only one request at a time; doing this should minimize
            the potential for failed deliveries, as GitHub's webhook delivery service
            times out very quickly
        
        Fixed:
        * GitHub URL regexes should match all possible usernames & repo names (#38)
          * Of particular note: dots (`.`) are now recognized in repository links,
            such as Sopel's website repo: https://github.com/sopel-irc/sopel.chat
        
        
        Changes in 0.1.7
        ================
        
        Fixed:
        * Error with empty issue/PR description or commit message (#39)
        
        
        Changes in 0.1.6
        ================
        
        Changed:
        * Webhook now says "merged" instead of "closed" for merged PRs (#18)
        * Re-opened issues/PRs will also trigger the webhook now (#27)
        
        Fixed:
        * Webhook ignores issue, PR, and review comments that were edited (#16, #24)
        * Commit summary correctly says "1 file" instead of "1 files" (#37)
        * Some webhook output grammar fixed (#15)
        * Handle comments submitted via email correctly WRT line-endings (#30)
        * Replace uses of long-deprecated `SopelMemory` method (#33)
        
        
        Changes in 0.1.5
        ================
        
        Fixed:
        * Refactoring unintentionally broke registering new repo webhooks (#14)
        
        Meta:
        * PyPI package description should be rendered to HTML now (fixed content-type)
        
        
        Changes in 0.1.4
        ================
        
        Changed:
        * "GitHub" is now properly capitalized everywhere in text output (#9)
        * Usage output uses `help_prefix` from config instead of hardcoded `.` (#12)
        
        Fixed:
        * git.io shortening was cutting off GET parameters of input links. (#11)
        
        
        Changes in 0.1.3
        ================
        
        Meta:
        * Moved to Sopel organization on GitHub; new maintainer
        
        Changed:
        * Uses requests instead of deprecated sopel.web functions (Sopel itself
          requires requests, so we don't have to.)
        * Fetched git.io links use HTTPS now
        
Platform: UNKNOWN
Description-Content-Type: text/markdown
