Metadata-Version: 2.1
Name: sopel_modules.github
Version: 0.2.0a15
Summary: GitHub module for Sopel
Home-page: https://github.com/sopel-irc/sopel-github
Author: Max Gurela
Author-email: maxpowa@outlook.com
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
         * Repositories
        
        Pretty prints repository details on command, using `.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, `:emoji_name:`s will be converted to Unicode emoji in the output.
        
        
        ### API Keys & Usage
        
        GitHub APIs have 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. There's
        two ways this may be configured, behind a proxy or 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 included in 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 the below
        config.
        ```
        [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.2.0a15
        ===================
        
        Fixed:
        * Actually fire event handler for PRs marked `ready_for_review`
        
        Changes in 0.1.7
        ================
        
        Fixed:
        * Error with empty issue/PR description or commit message (#39)
        
        
        Changes in 0.2.0a14
        ===================
        
        Fixed:
        * Empty issue/PR description or empty commit message won't throw errors any
          more (#39)
        
        
        Changes in 0.2.0a13
        ===================
        
        Changed:
        * Arrow character used in title edit output had limited mobile support; switched
          to one that appears to be available just about everywhere
        
        Fixed:
        * Stop trying to get milestone name for "demilestoned" payloads (GitHub
          doesn't send that information, unfortunately)
        
        Meta:
        * Alpha branch is now based on version 0.1.6
        
        
        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.2.0a12
        ===================
        
        Fixed:
        * Bad copy-paste-fu causing errors for PR title edits
        
        
        Changes in 0.2.0a11
        ===================
        
        Added:
        * Emit an event to IRC when an issue or PR title is edited (#36)
        
        
        Changes in 0.2.0a10
        ===================
        
        Added:
        * Emit an event to IRC when an issue or PR milestone is added/removed (#35)
        
        
        Changes in 0.2.0a9
        ==================
        
        Changed:
        * URL regexes should be more faithful to GitHub's actual restrictions
          * Neither usernames nor repo names can contain underscore (`_`), so we
            shouldn't accept it
          * Repo names can contain dot (`.`), which the old regex didn't allow
          * Usernames have a maximum length, which we are now looking for
        
        Fixed:
        * Unnecessary parentheses added in previous alpha release
          * Apparently, `pip install --upgrade --pre` can install the wrong release,
            making one's testing unreliable.
        
        
        Changes in 0.2.0a8
        ==================
        
        Fixed:
        * Developer stupidity regarding inline conditionals
        
        
        Changes in 0.2.0a7
        ==================
        
        Fixed:
        * Developer stupidity regarding types
        
        
        Changes in 0.2.0a6
        ==================
        
        Changed:
        * Handler for commit links now outputs "1 file" instead of "1 files" if the
          linked commit changed only one file
        
        
        Changes in 0.2.0a5
        ==================
        
        Added:
        * Webhook handling of draft pull requests (both opening and marking ready)
        
        Fixed:
        * Sopel's development version finally marked `SopelMemory.contains()` as
          deprecated, so we don't use it any more
        
        
        Changes in 0.2.0a4
        ==================
        
        Fixed:
        * Empty PR reviews caused HTTP 500 because of how they were skipped (they
          should now return HTTP 200 as normal)
        
        
        Changes in 0.2.0a3
        ==================
        
        Added:
        * Handle when issues/PRs are "reopened" (#27)
        
        
        Changes in 0.2.0a2
        ==================
        
        Fixed:
        * Polymorphism is hard in label/assignee events (getting the PR number caused
          errors because sometimes GitHub *does* use `pull_request` instead of `issue`)
        
        
        Changes in 0.2.0a1
        ==================
        
        Added:
        * Handle label & assignee events for PRs too, not just issues (#23)
        
        Changed:
        * Edits to review comments also ignored (#24)
        
        
        Changes in 0.2.0a0
        ==================
        
        Added:
        * Conversion of :emoji: to Unicode emoji in some places, if the required
          library is installed (#17)
        * Handling of PR reviews and release events (#20, #21)
        
        Changed:
        * Merged PRs are now distinct from closed PRs (#18)
        * Grammar updated, mostly around comment-type notifications (#15)
        * Edits to existing comments are ignored (no more duplicates) (#16)
        
        
        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
