purr-pr 0.1.7 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c4bbf318a7b60cfa3cd5c57416dd3f66764b99928e78330a7d04f69b7c095ca
-  data.tar.gz: 8040ce5923ece5149ab563b12b223fad7f3d705d80e37a7c9a71ff82237faa96
+  metadata.gz: 14bece028ed60daba6706c6c6432bb5768cf18c62dcadd03df6225b866a0b631
+  data.tar.gz: 59297880679407b4d96be5c4c5ac797f3e6a4feaf2478dbc413f08b38412aa3d
 SHA512:
-  metadata.gz: 5e2cc29dd764cecbf87bca385874511dd1c0eb677b2bf77a2fb7ee4e415d28f70a6fb98123fa16647d54bde0d94c43a0d59a2004cf8d8abd534404b9c6a1cd7a
-  data.tar.gz: 5dbeeec11460198a30528260c2e6964d9919669fa8084196b029f9ddbd3fb8e2eb12de87740bf1230db83b3a033610bd9399d0fe1807f107a2f7da256a3ff8ec
+  metadata.gz: b84b4c9ecb3cdd053c23f8c8e7c38ef272d30d41ab6cab4fe25d607722b6c75c0b4685fca73c77cbf6e0fd890ecff9e447f58abd2510ed902296afabe088452c
+  data.tar.gz: 30f8172bb8caecd33b812a98a4c9a6d8663bbe3b0b94299fcf8de51c097a50b3ddd843cae6643518b8845214280bd4e90f0493aad324b39d4d30de40b74f92f9

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    purr-pr (0.1.6)
+    purr-pr (0.1.7)
 
 GEM
   remote: https://rubygems.org/
@@ -32,7 +32,7 @@ PLATFORMS
 
 DEPENDENCIES
   bundler (~> 2.0)
-  pry
+  pry (~> 0.14.1)
   purr-pr!
   rake (~> 13.0)
   rspec (~> 3.0)

data/README.md

@@ -1,8 +1,6 @@
-# Purr
+# Purr PR
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/purr`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+Tired of formatting/writing the same PR text over and over again? Use Purr PR to create a simple formatting script!
 
 ## Installation
 
@@ -14,27 +12,348 @@ gem 'purr'
 
 And then execute:
 
-    $ bundle install
+```bash
+bundle install
+```
 
 Or install it yourself as:
 
-    $ gem install purr
+```bash
+gem install purr
+```
+
+### Dependencies
+
+This gem using [GitHub CLI tool](https://github.com/cli/cli) to conveniently create PRs, so you will need to [install it](https://github.com/cli/cli#installation) in order to use Purr PR.
 
 ## Usage
 
-TODO: Write usage instructions here
+After installing gem, create a `purr_pr.rb` file in the root of your git project. This file will describe your PRs.
+
+### Configuration
+
+Now you can use `purr_pr.rb` file to create your formatting script
+
+#### Body
+
+As body is the biggest PR part there are a lot of helpers to edit it. The base format is a:
+
+```ruby
+body do
+  # your edits
+end
+```
+
+##### Templates
+
+First of all the `use_template` method will simply copy the contents of `.github/pull_request_template.md` to a body buffer.
+To use any other file as a template you can provide the path to it as an argument:
+
+```ruby
+body do
+  use_template
+  # or use_template '.github/some_other_template.md'
+end
+```
+
+The above code will create a PR with body that has the contents of a PR template file, but this is what GitHub do by default, so then you'll probably want to apply some edits.
+
+For the future edits lets say that the contents of `.github/pull_request_template.md` is 'foo-template'
+
+To append or prepend some content to the buffer you can use corresponding methods:
+
+```ruby
+body do
+  use_template
+  append '-postfix'
+  prepend '[STORY_NUMBER] '
+end
+```
+
+It will create the next body: '[STORY_NUMBER] foo-template-postfix'.
+
+To change some text in a buffer use the `replace` method:
+
+```ruby
+body do
+  use_template
+  append '-postfix'
+  prepend '[STORY_NUMBER] '
+  replace '[STORY_NUMBER]', with: 1337
+end
+```
+
+=> '[1337] foo-template-postfix'.
+
+To remove some text use the `delete` method:
+
+```ruby
+body do
+  use_template
+  append '-postfix'
+  prepend '[STORY_NUMBER] '
+  replace '[STORY_NUMBER]', with: 1337
+  delete '-postfix'
+end
+```
+
+=> '[1337] foo-template'.
+
+You can conditionally clear the buffer with the `clear` method:
+
+```ruby
+body do
+  use_template
+  clear if ARGV.first == '--empty'
+end
+```
+
+The above code will create the PR with empty body if the first argument is '--empty'
+
+##### Manual edits
+
+You can also open the `$EDITOR` and manually edit the buffer text with `editor` method:
+
+```ruby
+body do
+  use_template
+  editor
+end
+```
+
+The above config will allow you to edit your template before creating a PR.
+Optionally you can provide file format to use syntax highlighting (the default is `:md`): `editor format: :html`.
+
+##### Confirmation
+
+If you whant to ensure that your edits are correct use `confirm` method, it will display you current buffer and ask Y/N confirmation to continue:
+
+```ruby
+body do
+  use_template
+  confirm
+end
+```
+
+##### Helpers
+
+There are some syntax sugar and helpers to be used as the arguments of above methods:
+
+```ruby
+body do
+  append newline(3)     # => '\n\n\n'
+  append space          # => ' '
+  append commits.last   # => Latest commit
+  append current_branch # => Current git branch
+end
+```
+
+##### Actions
+
+To ask a Y/N question you can use `ask_yn` method:
+
+```ruby
+body do
+  ask_yn 'wanna dance? (Y/N)', confirm: -> { append 'yeeesss' }, decline: -> { append 'nope :(' }
+end
+```
+
+The first argument is a message, and `:confirm` and `:decline` arguments are for callbacks.
+
+To ask for a custom input use the `ask` method:
+
+```ruby
+body do
+  append(ask 'Story number: ', default: 1337)
+end
+```
+
+It will prompt you to enter the story number and then append it to the buffer. If no input is provided the `:default` value will be used.
+To prompt for multiline input use `multiline: true`, it will prompt for the next line untill you input two empty lines in a row.
+Use `newline: true` to append an empty line after the input.
+
+To read a file there is a `read_file` method:
+
+```ruby
+body do
+  append(read_file('Gemfile'))
+end
+```
+
+The above config will append your Gemfile content to the buffer
+
+To conditionally finish the editing and create a PR use `finish`:
+
+```ruby
+body do
+  ask_yn 'are you a duck? (Y/N)', confirm: -> { append 'quack' }, decline: -> { finish }
+end
+```
+
+If you want to finish editing and cancel the PR creating you should use `interrupt` instead
+
+#### Title
+
+For PR title you can use the same block formatting as for the body:
+
+```ruby
+title do
+  story_number = "[#{current_branch}]"
+
+  append story_number
+  append ' my aweasome PR: '
+  append commits.last
+end
+```
+
+Or simply do:
+
+```ruby
+title 'My static PR title'
+```
+
+The first argument will be the initial title before editing, so:
+
+```ruby
+title 'Story#' do
+  append 1337
+end
+```
+
+Will create a title 'Story#1337'
+
+#### Assignee
+
+To assign someone to a PR use `assignee` or `self_assign` options:
+
+```ruby
+assignee '@JohnDoe'
+assignee '@me' # self-assign
+self_assign    # the same as above
+```
+
+#### Base branch
+
+If you want to change the default base branch use `base` option:
+
+```ruby
+base 'develop'
+```
+
+#### Draft PRs
+
+To create draft PR use `draft` option:
+
+```ruby
+draft
+# or
+draft true
+```
+
+#### Labels
+
+To add PR labels use `labels` or `label` options:
+
+```ruby
+labels ['bug', 'duplicate'] # to add as an array
+label 'documentation' # to add a single label
+```
+
+The above code will add `bug`, `duplicate` and `documentation` labels to the PR
+
+#### Reviewers
+
+To add reviewers use `reviewers` or `reviewer` options:
+
+```ruby
+reviewers ['@JohnDoe', '@BoJackHorseman'] # to add as an array
+reviewer '@FooBar' # to add a single label
+```
+
+The above code will add `@JohnDoe`, `@BoJackHorseman` and `@FooBar` as the reviewers to the PR
+
+#### Disabling maintainer edit
+
+To disable/reenable edits from maintainer use `maintainer_edit` or `no_maintainer_edit` options:
+
+```ruby
+maintainer_edit false
+no_maintainer_edit # the same as above
+```
+
+### Finally, create a PR!
+
+Simply call `purr` and it will create a PR for you via [GitHub CLI](https://github.com/cli/cli) according to your configuration file. Note that you may need to log in first with `gh auth login`.
+To override any config values you can append them to `purr` as a `gh pr create` [arguments](https://cli.github.com/manual/gh_pr_create), e.g. `purr --body foo` will create a PR with body 'foo' instead of the value from `purr.rb`.
+
+#### Scripting is the key
+
+The inline edits is pretty simple, but pretty useless as well, so don't forget that you can use any ruby code here to format your buffer.
+A nice example:
+
+```ruby
+title 'Story: ' do
+  story_number = current_branch.gsub('/').first
+
+  append story_number
+  append space
+
+  if commits.count == 1
+    append commits.last
+  else
+    append(ask 'Title: ', default: commits.last)
+  end
+end
+
+body do
+  story_number = current_branch.gsub('/').first
+
+  use_template
+
+  # Story number
+  replace '<STORY-NUMBER>', with: story_number
+
+  # PR Title and details
+  if commits.count == 1
+    replace 'Story Title', with: commits.last
+    replace 'Details go here', with: commits.last
+  else
+    story_title = ask 'Title: ', default: commits.last
+    details = ask 'Details: ', default: commits.last
+    replace 'Story Title', with: story_title
+    replace 'Details go here', with: details
+  end
+
+  # check the PR type checkboxes
+  case ARGV.first
+  when '--feature'
+    replace '- [ ] New feature', with: '- [x] New feature'
+  when '--bugfix'
+    replace '- [ ] Bug fix', with: '- [x] Bug fix'
+  when '--docs'
+    replace '- [ ] Documentation', with: '- [x] Documentation'
+  end
+
+  editor # to ensure and fix something
+end
+
+draft
+self_assign
+reviewer '@MyTeamLeadReviever'
+label 'bug' if ARGV.first == '--bugfix'
+```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rspec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `rake install`. To release a new version, update the version number in [version.rb](lib/purr_pr/version.rb), and then run `rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/ARtoriouSs/purr. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/ARtoriouSs/purr/blob/master/CODE_OF_CONDUCT.md).
 
-## License
+## [License](LICENSE.txt)
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 

data/bin/setup

@@ -5,4 +5,6 @@ set -vx
 
 bundle install
 
-# Do any other automated setup that you need to do here
+# test config
+touch purr.rb
+echo "title 'foo'" >> purr.rb

data/lib/purr_pr/config.rb

@@ -15,12 +15,12 @@ class PurrPr
       @labels = []
     end
 
-    def title(text = '', &block)
-      @title = edit(:title, content: text, &block)
+    def title(initial_content = '', &block)
+      @title = edit(:title, content: initial_content, &block)
     end
 
-    def body(text = '', &block)
-      @body = edit(:body, content: text, &block)
+    def body(initial_content = '', &block)
+      @body = edit(:body, content: initial_content, &block)
     end
 
     def assignee(assignee)

data/lib/purr_pr/text_objects.rb

@@ -5,5 +5,9 @@ class PurrPr
     def newline(count = 1)
       "\n" * count
     end
+
+    def space(count = 1)
+      ' ' * count
+    end
   end
 end

data/lib/purr_pr/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class PurrPr
-  VERSION = '0.1.7'
+  VERSION = '0.1.8'
 end

data/purr_pr.gemspec

@@ -7,8 +7,8 @@ Gem::Specification.new do |spec|
   spec.version     = PurrPr::VERSION
   spec.author      = 'Alexander Teslovskiy'
   spec.email       = 'artoriousso@gmail.com'
-  spec.summary     = 'A CLI pull request formatter'
-  spec.description = 'Purr PR is a tool to automate pull request formatting via GitHub CLI'
+  spec.summary     = 'CLI tool for quick pull request formatting'
+  spec.description = 'Tired of formatting/writing the same PR text over and over again? Use Purr PR to create a customizable formatting script!'
   spec.homepage    = 'https://github.com/ARtoriouSs/purr-pr'
   spec.license     = 'MIT'
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: purr-pr
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.1.8
 platform: ruby
 authors:
 - Alexander Teslovskiy
@@ -66,7 +66,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.14.1
-description: Purr PR is a tool to automate pull request formatting via GitHub CLI
+description: Tired of formatting/writing the same PR text over and over again? Use
+  Purr PR to create a customizable formatting script!
 email: artoriousso@gmail.com
 executables:
 - purr
@@ -124,7 +125,7 @@ requirements: []
 rubygems_version: 3.2.3
 signing_key:
 specification_version: 4
-summary: A CLI pull request formatter
+summary: CLI tool for quick pull request formatting
 test_files:
 - spec/purr_spec.rb
 - spec/spec_helper.rb