Update new methods (#326)

Author: wasabigeek

CHANGELOG.md

@@ -1,7 +1,8 @@
 ### 0.15.0 (Next)
 
-* [#323](https://github.com/slack-ruby/slack-ruby-client/pull/322): Require Faraday >= 1.0 - [@dblock](https://github.com/dblock).
-* [#323](https://github.com/slack-ruby/slack-ruby-client/pull/322): Upgrade slack-ruby-danger, rubocop, rubocop-rspec and rubocop-performance - [@dblock](https://github.com/dblock).
+* [#326](https://github.com/slack-ruby/slack-ruby-client/pull/326): Update new methods - [@wasabigeek](https://github.com/wasabigeek).
+* [#324](https://github.com/slack-ruby/slack-ruby-client/pull/324): Require Faraday >= 1.0 - [@dblock](https://github.com/dblock).
+* [#324](https://github.com/slack-ruby/slack-ruby-client/pull/324): Upgrade slack-ruby-danger, rubocop, rubocop-rspec and rubocop-performance - [@dblock](https://github.com/dblock).
 * [#322](https://github.com/slack-ruby/slack-ruby-client/pull/322): Cache `Faraday::Connection` for persistent adapters - [@drbrain](https://github.com/drbrain).
 * Your contribution here.
 

CONTRIBUTING.md

@@ -75,13 +75,31 @@ rake slack:api:update
 
 Sometimes it's necessary to patch auto-generated Slack Web API methods. For example, we want to help clients with calling `to_json` on the `attachments` parameter sent to `chat_postMessage`. See [#20](https://github.com/slack-ruby/slack-ruby-client/issues/20).
 
-Make a change to a generated file, for example `lib/slack/web/api/endpoints/chat.rb` and generate a patch.
+The broad steps are:
+1. Run `rake slack:api:update` to check that existing patches are still valid.
+    - If you run into a `failed to apply patch` error, the auto-generated methods likely drifted from the last patch. Follow the steps [below](#resolving-patch-errors).
+    - This may add new methods if the API has updated, please split them up into multiple PRs if so.
+2. Make a change to a generated file, for example `lib/slack/web/api/endpoints/chat.rb`.
+3. Generate a patch:
+    ```
+    git diff --no-color HEAD lib/slack/web/api/endpoints/chat.rb > lib/slack/web/api/patches/chat.1.patch
+    ```
+4. Run `rake slack:api:update` to ensure that the patch is cleanly applied. Implement a test for the added or modified functionality and commit the patch file.
+
+##### Resolving Patch Errors
+
+The auto-generated method files may drift overtime e.g. new arguments may be added or descriptions changed. Since previous patches were based on the older auto-generated files, git may be unable to apply them to the new files. Resolving them requires some good ol' splicing:
+1. Comment out the patching code in `lib/tasks/web.rake`:
+    ```ruby
+    # Dir.glob("lib/slack/web/api/patches/#{group}*.patch").sort.each do |patch|
+    #   puts "- patching #{patch}"
+    #   system("git apply #{patch}") || raise('failed to apply patch')
+    # end
+    ```
+2. Run `rake slack:api:update` to create the raw auto-generated files. Commit the files that you are updating, so we can run `git diff` later.
+3. Go through the old patches for the files (e.g. in `lib/slack/web/api/patches/chat.1.patch`), copying code into the new files.
+4. Continue with Step 2 [above](#patching-slack-web-api).
 
-```
-git diff --no-color HEAD lib/slack/web/api/endpoints/chat.rb > lib/slack/web/api/patches/chat.1.patch
-```
-
-Run `rake slack:api:update` to ensure that the patch is cleanly applied. Implement a test for the added or modified functionality and commit the patch file.
 
 ### Write Documentation
 

bin/commands/chat.rb

@@ -137,13 +137,13 @@
   g.long_desc %( Updates a message. )
   g.command 'update' do |c|
     c.flag 'channel', desc: 'Channel containing the message to be updated.'
-    c.flag 'text', desc: "New text for the message, using the default formatting rules. It's not required when presenting attachments."
     c.flag 'ts', desc: 'Timestamp of the message to be updated.'
     c.flag 'as_user', desc: 'Pass true to update the message as the authed user. Bot users in this context are considered authed users.'
-    c.flag 'attachments', desc: 'A JSON-based array of structured attachments, presented as a URL-encoded string. This field is required when not presenting text.'
-    c.flag 'blocks', desc: 'A JSON-based array of structured blocks, presented as a URL-encoded string.'
-    c.flag 'link_names', desc: 'Find and link channel names and usernames. Defaults to none. See below.'
-    c.flag 'parse', desc: 'Change how messages are treated. Defaults to client, unlike chat.postMessage. See below.'
+    c.flag 'attachments', desc: "A JSON-based array of structured attachments, presented as a URL-encoded string. This field is required when not presenting text. If you don't include this field, the message's previous attachments will be retained. To remove previous attachments, include an empty array for this field."
+    c.flag 'blocks', desc: "A JSON-based array of structured blocks, presented as a URL-encoded string. If you don't include this field, the message's previous blocks will be retained. To remove previous blocks, include an empty array for this field."
+    c.flag 'link_names', desc: 'Find and link channel names and usernames. Defaults to none. If you do not specify a value for this field, the original value set for the message will be overwritten with the default, none.'
+    c.flag 'parse', desc: 'Change how messages are treated. Defaults to client, unlike chat.postMessage. Accepts either none or full. If you do not specify a value for this field, the original value set for the message will be overwritten with the default, client.'
+    c.flag 'text', desc: "New text for the message, using the default formatting rules. It's not required when presenting blocks or attachments."
     c.action do |_global_options, options, _args|
       puts JSON.dump($client.chat_update(options))
     end

lib/slack/web/api/endpoints/chat.rb

@@ -259,20 +259,20 @@ def chat_unfurl(options = {})
           #
           # @option options [channel] :channel
           #   Channel containing the message to be updated.
-          # @option options [Object] :text
-          #   New text for the message, using the default formatting rules. It's not required when presenting attachments.
           # @option options [timestamp] :ts
           #   Timestamp of the message to be updated.
           # @option options [Object] :as_user
           #   Pass true to update the message as the authed user. Bot users in this context are considered authed users.
           # @option options [Object] :attachments
-          #   A JSON-based array of structured attachments, presented as a URL-encoded string. This field is required when not presenting text.
+          #   A JSON-based array of structured attachments, presented as a URL-encoded string. This field is required when not presenting text. If you don't include this field, the message's previous attachments will be retained. To remove previous attachments, include an empty array for this field.
           # @option options [Object] :blocks
-          #   A JSON-based array of structured blocks, presented as a URL-encoded string.
+          #   A JSON-based array of structured blocks, presented as a URL-encoded string. If you don't include this field, the message's previous blocks will be retained. To remove previous blocks, include an empty array for this field.
           # @option options [Object] :link_names
-          #   Find and link channel names and usernames. Defaults to none. See below.
+          #   Find and link channel names and usernames. Defaults to none. If you do not specify a value for this field, the original value set for the message will be overwritten with the default, none.
           # @option options [Object] :parse
-          #   Change how messages are treated. Defaults to client, unlike chat.postMessage. See below.
+          #   Change how messages are treated. Defaults to client, unlike chat.postMessage. Accepts either none or full. If you do not specify a value for this field, the original value set for the message will be overwritten with the default, client.
+          # @option options [Object] :text
+          #   New text for the message, using the default formatting rules. It's not required when presenting blocks or attachments.
           # @see https://api.slack.com/methods/chat.update
           # @see https://github.com/slack-ruby/slack-api-ref/blob/master/methods/chat/chat.update.json
           def chat_update(options = {})

…i/patches/chat.6.block-kit-support.patch lib/slack/web/api/patches/chat.1.patchlib/slack/web/api/patches/chat.6.block-kit-support.patch renamed to lib/slack/web/api/patches/chat.1.patch lib/slack/web/api/patches/chat.6.block-kit-support.patch renamed to lib/slack/web/api/patches/chat.1.patch

@@ -1,20 +1,23 @@
 diff --git a/lib/slack/web/api/endpoints/chat.rb b/lib/slack/web/api/endpoints/chat.rb
-index 54a7db1..c535bb5 100644
+index dede9c8..94f7085 100644
 --- a/lib/slack/web/api/endpoints/chat.rb
 +++ b/lib/slack/web/api/endpoints/chat.rb
-@@ -97,7 +97,7 @@ module Slack
+@@ -121,11 +121,22 @@ module Slack
+           # @see https://api.slack.com/methods/chat.postEphemeral
            # @see https://github.com/slack-ruby/slack-api-ref/blob/master/methods/chat/chat.postEphemeral.json
            def chat_postEphemeral(options = {})
+-            throw ArgumentError.new('Required arguments :attachments missing') if options[:attachments].nil?
              throw ArgumentError.new('Required arguments :channel missing') if options[:channel].nil?
--            throw ArgumentError.new('Required arguments :text or :attachments missing') if options[:text].nil? && options[:attachments].nil?
+-            throw ArgumentError.new('Required arguments :text missing') if options[:text].nil?
 +            throw ArgumentError.new('Required arguments :text, :attachments or :blocks missing') if options[:text].nil? && options[:attachments].nil? && options[:blocks].nil?
              throw ArgumentError.new('Required arguments :user missing') if options[:user].nil?
              options = options.merge(user: users_id(options)['user']['id']) if options[:user]
-             # attachments must be passed as an encoded JSON string
-@@ -106,6 +106,12 @@ module Slack
-               attachments = JSON.dump(attachments) unless attachments.is_a?(String)
-               options = options.merge(attachments: attachments)
-             end
++            # attachments must be passed as an encoded JSON string
++            if options.key?(:attachments)
++              attachments = options[:attachments]
++              attachments = JSON.dump(attachments) unless attachments.is_a?(String)
++              options = options.merge(attachments: attachments)
++            end
 +            # blocks must be passed as an encoded JSON string
 +            if options.key?(:blocks)
 +              blocks = options[:blocks]
@@ -24,18 +27,18 @@ index 54a7db1..c535bb5 100644
              post('chat.postEphemeral', options)
            end
 
-@@ -146,13 +152,19 @@ module Slack
+@@ -166,7 +177,19 @@ module Slack
            # @see https://github.com/slack-ruby/slack-api-ref/blob/master/methods/chat/chat.postMessage.json
            def chat_postMessage(options = {})
              throw ArgumentError.new('Required arguments :channel missing') if options[:channel].nil?
--            throw ArgumentError.new('Required arguments :text or :attachments missing') if options[:text].nil? && options[:attachments].nil?
+-            throw ArgumentError.new('Required arguments :text missing') if options[:text].nil?
 +            throw ArgumentError.new('Required arguments :text, :attachments or :blocks missing') if options[:text].nil? && options[:attachments].nil? && options[:blocks].nil?
-             # attachments must be passed as an encoded JSON string
-             if options.key?(:attachments)
-               attachments = options[:attachments]
-               attachments = JSON.dump(attachments) unless attachments.is_a?(String)
-               options = options.merge(attachments: attachments)
-             end
++            # attachments must be passed as an encoded JSON string
++            if options.key?(:attachments)
++              attachments = options[:attachments]
++              attachments = JSON.dump(attachments) unless attachments.is_a?(String)
++              options = options.merge(attachments: attachments)
++            end
 +            # blocks must be passed as an encoded JSON string
 +            if options.key?(:blocks)
 +              blocks = options[:blocks]
@@ -45,19 +48,19 @@ index 54a7db1..c535bb5 100644
              post('chat.postMessage', options)
            end
 
-@@ -204,7 +216,7 @@ module Slack
+@@ -254,8 +277,21 @@ module Slack
            # @see https://github.com/slack-ruby/slack-api-ref/blob/master/methods/chat/chat.update.json
            def chat_update(options = {})
              throw ArgumentError.new('Required arguments :channel missing') if options[:channel].nil?
--            throw ArgumentError.new('Required arguments :text or :attachments missing') if options[:text].nil? && options[:attachments].nil?
 +            throw ArgumentError.new('Required arguments :text, :attachments or :blocks missing') if options[:text].nil? && options[:attachments].nil? && options[:blocks].nil?
              throw ArgumentError.new('Required arguments :ts missing') if options[:ts].nil?
              options = options.merge(channel: channels_id(options)['channel']['id']) if options[:channel]
-             # attachments must be passed as an encoded JSON string
-@@ -213,6 +225,12 @@ module Slack
-               attachments = JSON.dump(attachments) unless attachments.is_a?(String)
-               options = options.merge(attachments: attachments)
-             end
++            # attachments must be passed as an encoded JSON string
++            if options.key?(:attachments)
++              attachments = options[:attachments]
++              attachments = JSON.dump(attachments) unless attachments.is_a?(String)
++              options = options.merge(attachments: attachments)
++            end
 +            # blocks must be passed as an encoded JSON string
 +            if options.key?(:blocks)
 +              blocks = options[:blocks]