sheets_v4 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aaee6f486ac124cdefd974acfe3f18357ade8e9f90655a46e746ebfad53a391b
-  data.tar.gz: 0f3c1e513b45a841052be82817e5bcf157aba492282999f401bb069e048e2263
+  metadata.gz: 0e42d894f2be3f646b39758c38a76d3c035047c2397e5ff37d03d84ab027dd0e
+  data.tar.gz: 461f2acf46f01fd2e26a20bbdda0e40a13700d13348fb879b6ee825f37f12375
 SHA512:
-  metadata.gz: c3762e42b88065e6bc76e5e749d629dc02073c2584053a9c979fd8b46196e70e155c2f06d87a768b511a93b30d38d09c5da6592ef875a9fb70cb7bd97b67ed7a
-  data.tar.gz: 64bed7345bcc3ee05d204b47770b297e8a53d05cc1deb6611bd114197cb46690df2683549e772b7b9453fbf158eba492efc05faf93e966047f57055e9d203d87
+  metadata.gz: ef2a81afffe0e2c8514c9df98dd6444d24e87924b957cb320604ba2705e5aa161f4fb0e87a06c9da5eda666a34f2cf9ea9316023f123116af98dc69eaeb8e553
+  data.tar.gz: ed191d55200c3f04bc5ec66390bc83f0c0538062c75c7e3a74211530718933ed8722a3bf8dbf06af7658f587906da3e6124d6339e18feb20bb33618a9fb25af5

data/.commitlintrc.yml

@@ -0,0 +1,16 @@
+---
+extends: '@commitlint/config-conventional'
+
+rules:
+  # See: https://commitlint.js.org/reference/rules.html
+  #
+  # Rules are made up by a name and a configuration array. The configuration array contains:
+  #
+  # * Severity [0..2]: 0 disable rule, 1 warning if violated, or 2 error if violated
+  # * Applicability [always|never]: never inverts the rule
+  # * Value: value to use for this rule
+  #
+  # Run `npx commitlint --print-config` to see the current setting for all rules.
+  #
+  body-leading-blank:    [2, 'always']
+  footer-leading-blank:  [2, 'always']

data/.husky/commit-msg

@@ -0,0 +1 @@
+npx --no-install commitlint --edit "$1"

data/.markdownlint.yml

@@ -9,7 +9,7 @@ MD013: { line_length: 90, tables: false, code_blocks: false }
 # Heading duplication is allowed for non-sibling headings
 MD024: { siblings_only: true }
 
-# Do not allow the specified trailig punctuation in a header
+# Do not allow the specified trailing punctuation in a header
 MD026: { punctuation: '.,;:' }
 
 # Order list items must have a prefix that increases in numerical order

data/.rubocop.yml

@@ -1,37 +1,7 @@
+inherit_gem:
+  main_branch_shared_rubocop_config: config/rubocop.yml
+
 AllCops:
-  NewCops: enable
-  # Output extra information for each offense to make it easier to diagnose:
-  DisplayCopNames: true
-  DisplayStyleGuide: true
-  ExtraDetails: true
-  SuggestExtensions: false
-  # RuboCop enforces rules depending on the oldest version of Ruby which
-  # your project supports:
+  # Pin this project to Ruby 3.1 in case the shared config above is upgraded to 3.2
+  # or later.
   TargetRubyVersion: 3.1
-
-Gemspec/DevelopmentDependencies:
-  EnforcedStyle: gemspec
-
-# The default max line length is 80 characters
-Layout/LineLength:
-  Max: 120
-
-# The DSL for RSpec and the gemspec file make it very hard to limit block length:
-Metrics/BlockLength:
-  Exclude:
-    - "spec/spec_helper.rb"
-    - "spec/**/*_spec.rb"
-    - "*.gemspec"
-
-Metrics/ModuleLength:
-  CountAsOne: ['hash']
-
-# When writing minitest tests, it is very hard to limit test class length:
-Metrics/ClassLength:
-  CountAsOne: ['hash']
-  Exclude:
-    - "test/**/*_test.rb"
-
-Style/AsciiComments:
-  Enabled: false
-

data/.yardopts

@@ -3,4 +3,6 @@
 --markup-provider=redcarpet
 --markup markdown
 - CHANGELOG.md
-- LICENSE.txt
+- CONTRIBUTING.md
+- RELEASING.md
+- LICENSE.txt

data/CHANGELOG.md

@@ -4,6 +4,41 @@ Changes for each release are listed in this file.
 
 This project adheres to [Semantic Versioning](https://semver.org/) for its releases.
 
+## v0.10.0 (2024-10-11)
+
+[Full Changelog](https://github.com/main-branch/sheets_v4/compare/v0.9.0..v0.10.0)
+
+Changes since v0.9.0:
+
+* 96d390e build: remove semver pr label check
+* 54149ee build: enforce conventional commit message formatting
+* 29ef270 Use shared Rubocop config
+* 39a926d Update copyright notice in this project
+* f4be18a Update links in gemspec
+* 9c6eae1 Add Slack badge for this project in README
+* eae2952 Update yardopts with new standard options
+* 24d501c Use standard badges at the top of the README
+* 0fb15d3 Standardize YARD and Markdown Lint configurations
+* 07db14a Set JRuby --debug option when running tests in GitHub Actions workflows
+* fe810d9 Integrate simplecov-rspec into the project
+* 256ac35 Update continuous integration and experimental ruby builds
+* 3f58109 Enforce the use of semver tags on PRs
+* 9be5038 Auto correct Rubocop Gemspec/AddRuntimeDependency offenses
+* c800d10 Add links to other gems in the Google API helpers series (#35)
+* 207c4d6 Reformat examples/README.md (#34)
+* 18b4d9b Move api_object_validation to the discovery_v1 gem (#33)
+* cc48f8c Review and update documentation (#32)
+* 2f2c8e2 Remove code for no longer used validate_api_object (#31)
+* e566cfe Reformat examples (#30)
+
+## v0.9.0 (2023-10-16)
+
+[Full Changelog](https://github.com/main-branch/sheets_v4/compare/v0.8.0..v0.9.0)
+
+Changes since v0.8.0:
+
+* 8fd7ec5 Add convenience methods to Spreadsheet to access Sheets (#28)
+
 ## v0.8.0 (2023-10-15)
 
 [Full Changelog](https://github.com/main-branch/sheets_v4/compare/v0.7.0..v0.8.0)

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2023 James Couball
+Copyright (c) 2024 James Couball
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -3,21 +3,35 @@
 [![Gem Version](https://badge.fury.io/rb/sheets_v4.svg)](https://badge.fury.io/rb/sheets_v4)
 [![Documentation](https://img.shields.io/badge/Documentation-Latest-green)](https://rubydoc.info/gems/sheets_v4/)
 [![Change Log](https://img.shields.io/badge/CHANGELOG-Latest-green)](https://rubydoc.info/gems/sheets_v4/file/CHANGELOG.md)
-[![Build Status](https://github.com/main-branch/sheets_v4/workflows/CI%20Build/badge.svg?branch=main)](https://github.com/main-branch/sheets_v4/actions?query=workflow%3ACI%20Build)
+[![Build Status](https://github.com/main-branch/sheets_v4/actions/workflows/continuous_integration.yml/badge.svg)](https://github.com/main-branch/sheets_v4/actions/workflows/continuous_integration.yml)
 [![Maintainability](https://api.codeclimate.com/v1/badges/aeebc016487c5cad881e/maintainability)](https://codeclimate.com/github/main-branch/sheets_v4/maintainability)
 [![Test Coverage](https://api.codeclimate.com/v1/badges/aeebc016487c5cad881e/test_coverage)](https://codeclimate.com/github/main-branch/sheets_v4/test_coverage)
+[![Conventional
+Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits&logoColor=white)](https://conventionalcommits.org)
+[![Slack](https://img.shields.io/badge/slack-main--branch/sheets__v4-yellow.svg?logo=slack)](https://main-branch.slack.com/archives/C07N5ULJQU9)
 
-Unofficial helpers for the Google Sheets V4 API
+Unofficial helpers and extensions for the Google Sheets V4 API
 
+Gems in the Google API helper, extensions, and examples series:
+
+* [discovery_v1](https://github.com/main-branch/discovery_v1)
+* [drive_v3](https://github.com/main-branch/drive_v3)
+* [sheets_v4](https://github.com/main-branch/sheets_v4)
+
+## Contents
+
+* [Contents](#contents)
 * [Installation](#installation)
+* [Examples](#examples)
 * [Important links for programming Google Sheets](#important-links-for-programming-google-sheets)
+  * [SheetsV4 documenation](#sheetsv4-documenation)
   * [General API documentation](#general-api-documentation)
   * [Ruby implementation of the Sheets API](#ruby-implementation-of-the-sheets-api)
-  * [Other Links](#other-links)
-* [Getting Started](#getting-started)
-  * [Creating a Google Cloud project](#creating-a-google-cloud-project)
+  * [Other links](#other-links)
+* [Getting started](#getting-started)
+  * [Create a Google Cloud project](#create-a-google-cloud-project)
   * [Enable the APIs you want to use](#enable-the-apis-you-want-to-use)
-  * [Create a Google API credentials](#create-a-google-api-credentials)
+  * [Download a Google API credential file](#download-a-google-api-credential-file)
 * [Usage](#usage)
   * [Obtaining an authenticated SheetsService](#obtaining-an-authenticated-sheetsservice)
   * [Building a request](#building-a-request)
@@ -30,9 +44,11 @@ Unofficial helpers for the Google Sheets V4 API
     * [Spreadsheet Extensions](#spreadsheet-extensions)
     * [Sheet Extensions](#sheet-extensions)
   * [Working with dates and times](#working-with-dates-and-times)
-  * [Colors](#colors)
+  * [Working with colors](#working-with-colors)
 * [Development](#development)
 * [Contributing](#contributing)
+  * [Commit message guidelines](#commit-message-guidelines)
+  * [Pull request guidelines](#pull-request-guidelines)
 * [License](#license)
 
 ## Installation
@@ -49,8 +65,28 @@ If bundler is not being used to manage dependencies, install the gem by executin
 gem install sheets_v4
 ```
 
+## Examples
+
+Many examples can be found in the `examples` directory of this project. The examples
+have [a README of their own](https://github.com/main-branch/sheets_v4/tree/reformat_examples/examples)
+which describes each example.
+
+Prior to running an example, clone this project and run `bundle install` in the
+project's root working directory.
+
+Run an example using `bundle exec`. For example, to run the `set_background_color1`
+example:
+
+```shell
+bundle exec examples/set_background_color1
+```
+
 ## Important links for programming Google Sheets
 
+### SheetsV4 documenation
+
+This Gem's YARD documentation is hosted on [rubydoc.info]https://rubydoc.info/gems/sheets_v4/.
+
 ### General API documentation
 
 * [Google Sheets API Overview](https://developers.google.com/sheets/api)
@@ -63,29 +99,31 @@ gem install sheets_v4
 * [SheetsService Class](https://github.com/googleapis/google-api-ruby-client/blob/main/generated/google-apis-sheets_v4/lib/google/apis/sheets_v4/service.rb)
 * [All Other Sheets Classes](https://github.com/googleapis/google-api-ruby-client/blob/main/generated/google-apis-sheets_v4/lib/google/apis/sheets_v4/classes.rb)
 
-### Other Links
+### Other links
 
 * [Apps Script for Sheets](https://developers.google.com/apps-script/guides/sheets)
 
-## Getting Started
+## Getting started
 
-In order to use this gem, you will need to obtain a Google API sheets service
+In order to use this gem, you will need to obtain a Google API service account
 credential following the instructions below.
 
-### Creating a Google Cloud project
+### Create a Google Cloud project
 
 Create a Google Cloud project using [these directions](https://developers.google.com/workspace/guides/create-project).
 
 ### Enable the APIs you want to use
 
 Enable the Sheets API for this project using [these directions](https://developers.google.com/workspace/guides/enable-apis).
+Optionally, enable the Drive API since you may need it to create a spreadsheet.
 
-### Create a Google API credentials
+### Download a Google API credential file
 
-Create a service account and download credentials using [these directions](https://developers.google.com/workspace/guides/create-credentials#service-account).
+Create a service account and download a credential file using [these directions](https://developers.google.com/workspace/guides/create-credentials#service-account).
 
-You can store the download credential files anywhere on your system. The recommended
-location is `~/.google-api-credential.json`.
+You can store the download credential files anywhere on your system.
+The recommended location is `~/.google-api-credential.json` since this is default
+credential file that `SheetsV4.sheets_service` uses.
 
 ## Usage
 
@@ -115,8 +153,8 @@ an authenticated SheetsService object can be obtained with one method call:
 sheets_service = SheetsV4.sheets_service
 ```
 
-If the credential is stored elsewhere, pass the credential_source to `SheetsV4.sheets_service`
-manually. `credential_source` can be a String:
+If the credential is stored somewhere else, pass the `credential_source` to
+`SheetsV4.sheets_service` manually. `credential_source` can be a String:
 
 ```Ruby
 sheets_service = SheetsV4.sheets_service(credential_source: File.read('credential.json'))
@@ -253,29 +291,40 @@ Google Sheets API will do one of following depending on the nature of the proble
    common result)
 3. Not return an error with some of the batch requests not having the expected outcome
 
-Luckily, this library provides a way to validate that requests are valid and
-identifies precisely where the request objects do not conform to the API description.
+Luckily, you can validate that requests are valid and identifies precisely where
+the request objects do not conform to the API description using the DiscoveryV1 API.
 That is the subject of the next section [Validating requests](#validating-requests).
 
 ### Validating requests
 
-The [`SheetsV4.validate_api_object`](https://rubydoc.info/gems/sheets_v4/SheetsV4#validate_api_object-class_method)
-method can be used to validate request objects prior to using them in the Google
-Sheets API.
+Use the [DiscoveryV1 API](https://github.com/main-branch/discovery_v1)
+can be used to validate request object prior to using them in the Google Sheets API.
 
-This method takes a `schema_name` and an `object` to validate. Schema names can be
-listed using [`SheetsV4.api_object_schema_names`](https://rubydoc.info/gems/sheets_v4/SheetsV4#api_object_schema_names-class_method).
+In this API, [`DiscoveryV1.validate_object`](https://rubydoc.info/gems/discovery_v1/DiscoveryV1#validate_object-class_method)
+validates a request object for a given schema. This method takes a `schema_name`
+and an `object` to validate. Valid schemas names for an API can be listed using
+[`SheetsV4.api_object_schema_names`](https://rubydoc.info/gems/sheets_v4/SheetsV4#api_object_schema_names-class_method).
 
-This method will either return `true` if `object` conforms to the schema OR it
+`validate_object` will either return `true` if `object` conforms to the schema OR it
 will raise a RuntimeError noting where the object structure did not conform to
 the schema.
 
 In the previous examples (see [Building a request](#building-a-request)), the
-following line can be inserted after the `requests =  ...` line to validate the
+following lines can be inserted after the `requests =  ...` line to validate the
 request:
 
 ```Ruby
-SheetsV4.validate_api_object(schema: 'batch_update_spreadsheet_request', object: requests)
+require 'discovery_v1'
+discovery_service = DiscoveryV1.discovery_service
+rest_description = discovery_service.get_rest_api('sheets', 'v4')
+schema_name = 'batch_update_spreadsheet_request'
+object = requests
+begin
+  DiscoveryV1.validate_object(rest_description:, schema_name:, object:)
+  puts 'BatchUpdateSpreadsheetRequest object is valid'
+rescue RuntimeError => e
+  puts e.message
+end
 ```
 
 ### Google Extensions
@@ -303,6 +352,13 @@ sheets_service, spreadsheet, and sheet objects separately.
 
 The `sheets_service` attribute is added and is set by `SheetsService#get_spreadsheet`.
 
+Convenience methods for getting sheets within the spreadsheet are added:
+
+* `sheet(id_or_title)`: returns the sheet matching the id or title given
+* `sheet_id(title)`: returns the ID  for the sheet matching the title given
+* `each_sheet(ids_or_titles)`: enumerates the sheets within a spreadsheet matching
+  the given IDs or titles.
+
 #### Sheet Extensions
 
 The `sheets_service` and `spreadsheet` attributes are added. Both are set when the
@@ -371,7 +427,7 @@ datetime = SheetsV4.gs_to_datetime(cell_value) #=> Mon, 17 May 2021 04:36:00 -07
 datetime.utc #=> 2021-05-17 11:36:00 UTC
 ```
 
-### Colors
+### Working with colors
 
 Color objects (with appropriate :red, :green, :blue values) can be retrieved by name
 using `SheetsV4.color(:black)` or `SheetsV4::Color.black` (these are equivalent).
@@ -400,6 +456,31 @@ commits and the created tag, and push the `.gem` file to
 
 Bug reports and pull requests are welcome on [the main-branch/sheets_v4 GitHub project](https://github.com/main-branch/sheets_v4).
 
+### Commit message guidelines
+
+All commit messages must follow the [Conventional Commits
+standard](https://www.conventionalcommits.org/en/v1.0.0/). This helps us maintain a
+clear and structured commit history, automate versioning, and generate changelogs
+effectively.
+
+To ensure compliance, this project includes:
+
+* A git commit-msg hook that validates your commit messages before they are accepted.
+
+  To activate the hook, you must have node installed and run `npm install`.
+
+* A GitHub Actions workflow that will enforce the Conventional Commit standard as
+  part of the continuous integration pipeline.
+
+  Any commit message that does not conform to the Conventional Commits standard will
+  cause the workflow to fail and not allow the PR to be merged.
+
+### Pull request guidelines
+
+All pull requests must be merged using rebase merges. This ensures that commit
+messages from the feature branch are preserved in the release branch, keeping the
+history clean and meaningful.
+
 ## License
 
 The gem is available as open source under the terms of the

data/Rakefile

@@ -48,17 +48,9 @@ CLEAN << 'rspec-report.xml'
 
 require 'rubocop/rake_task'
 
-RuboCop::RakeTask.new do |t|
-  t.options = %w[
-    --display-cop-names
-    --display-style-guide
-    --extra-details
-    --format progress
-    --format json --out rubocop-report.json
-  ]
-end
+RuboCop::RakeTask.new
 
-CLEAN << 'rubocop-report.json'
+# YARD
 
 unless RUBY_PLATFORM == 'java'
   # yard:build