Changes requested in documentation review (#7)

Author: jcouball

.yardopts

@@ -2,3 +2,4 @@
 --hide-void-return
 --markup-provider=redcarpet
 --markup markdown
+- CHANGELOG.md CONTRIBUTING.md MAINTAINERS.md RELEASING.md LICENSE.md

CONTRIBUTING.md

@@ -59,7 +59,7 @@ request meets [the project's coding standards](#coding-standards).
 
 ## Coding standards
 
-In order to ensure high quality, all pull requests must meet these requirements:
+All pull requests must meet these requirements:
 
 ### 1 PR = 1 Commit
   * All commits for a PR must be squashed into one commit
@@ -76,14 +76,21 @@ In order to ensure high quality, all pull requests must meet these requirements:
 ### Documentation
   * New and updated public methods must have [YARD](https://yardoc.org/)
     documentation added to them
+      * [The YARD Cheatsheet](https://gist.github.com/thelastinuit/5984665e6ab69d3c0a413a03602c45be)
+        is a good reference
   * New and updated public facing features should be documented in the project's
     [README.md](README.md)
-  * All documentation must pass `yardstick` documentation analysis. 
+  * All documentation must pass `yardstick` documentation analysis
   * The documentation suite must maintain 100% documentation to pass
 
 ### Continuous Integration
   * All tests must pass in the project's [Travis CI](https://travis-ci.org/jcouball/ruby_git)
-    build before the pull request will be merged
+    build before the pull request will be merged.
+  * You can simulate what happens in the Travis CI build by running `bundle exec rake` in 
+    the projects root directory.
+
+### Other Design Guidelines
+  * Use keyword args with defaults instead of an opts hash
 
 ## Licensing
 

MAINTAINERS.md

@@ -0,0 +1,8 @@
+# Maintainers
+
+When making changes in this repository, one of the maintainers below must review
+and approve your pull request.
+
+### Maintainers
+
+* [James Couball](https://github.com/jcouball)

README.md

@@ -6,7 +6,9 @@
 [![Maintainability](https://api.codeclimate.com/v1/badges/2d8d52a55d655b6a3def/maintainability)](https://codeclimate.com/github/jcouball/ruby_git/maintainability)
 
 RubyGit is an object-oriented wrapper for the `git` command line tool for working with Worktrees
-and Repositories. It tries to make more sense out of the Git command line. 
+and Repositories. It tries to make more sense out of the Git command line. See the object model
+in [this Lucid chart diagram](https://app.lucidchart.com/invitations/accept/7df13bab-3383-4683-8cb4-e76d539de93d)
+(requires sign in).
 
 ## Installation
 
@@ -66,14 +68,11 @@ The full API is documented in [the RubyGit YARD documentation](https://github.co
 
 ## 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
+`bundle exec rake` to run tests, static analysis, and build the gem.
 
-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 tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+For experimentation, you can also run `bin/console` for an interactive (IRB) prompt that
+automatically requires ruby_git.
 
 ## Contributing
 

RELEASING.md

@@ -17,9 +17,11 @@ version number, (2) update the CHANGELOG.md, and (3) tag the release.
     guidelines
   * Add a link in CHANGELOG.md to the release tag which will be created later
     in this guide
+  * `git add` these changes to the index, but do not commit them.
   * Create a new tag using [git-extras](https://github.com/tj/git-extras/blob/main/Commands.md#git-release)
     `git release` command
     * For example: `git release v1.1.0.pre1`
+    * This will create a commit for the tag and any changes in the index.
   * These should be the only changes in the PR
   * Get the PR reviewed, approved and merged to main.
 

lib/ruby_git/git_binary.rb

@@ -26,8 +26,8 @@ def initialize
     #
     # @return [Pathname]
     #
-    # @raise [RuntimeError] A RuntimeError is raised when the path is not to an
-    #   existing executable file.
+    # @raise [RuntimeError] A RuntimeError is raised when the path does not refer
+    #   to an existing executable file.
     #
     def path=(path)
       new_path = Pathname.new(path)
@@ -64,7 +64,7 @@ def path
     # @return [Pathname] the path to the git binary found in the path
     #
     # @raise [RuntimeError] if either PATH is not set or an executable file
-    #   basename was not found on the path.
+    #   `basename` was not found on the path.
     #
     def self.default_path(basename: 'git')
       RubyGit::FileHelpers.which(basename) || raise("Could not find '#{basename}' in the PATH.")

ruby_git.gemspec

@@ -18,7 +18,12 @@ Gem::Specification.new do |spec|
   DESCRIPTION
   spec.homepage = 'https://github.com/pages/jcouball/ruby_git/'
   spec.required_ruby_version = Gem::Requirement.new('>= 2.6.0')
-  spec.requirements = ['git 2.18.0 or later']
+  spec.requirements = [
+    'Git 2.18.0 or later',
+    'Ruby 2.6 or later',
+    'Only MRI Ruby and JRuby are officially supported.',
+    'Mac, Linux, Unix, and Windows platforms are supported'
+  ]
 
   spec.metadata['allowed_push_host'] = 'https://rubygems.org'