ruby-jss 2.0.0b5 → 2.0.0rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b224082c515d1c12d50736092c859f7f21f1acbb8d6d3d98b861221362a64f7d
-  data.tar.gz: 7c10c43a7842be9fee1819bcc9a92457e1dce0d338e97f6a00eeb27d1f75416b
+  metadata.gz: 89974abcf43374bb65bbb1e0e91a2c147b0a28e7143f8f5e995c372c7ecdef7d
+  data.tar.gz: 720708403ca790ca523b11cedffa5c4c218f67720bc0ef3cce57f97ef9ce7490
 SHA512:
-  metadata.gz: 32378337e65ccc32c836217434cdfa7fe060d400268848174a675fcbb163157e0d0965e4141fbbe35eef60bd042cca58777189db18d641e1dd1d6ab7ed4d2f37
-  data.tar.gz: d24ca66815d7e4f0b5bc4a212463e985e490fe499c0b299b6df41f12f6943f156f2681ebf5696198a66853e593cbfe9fdd248948e02e4d2c67ccd910cccc900f
+  metadata.gz: b0e93ad88ec4cf67ae0200d5bd57b57b2a56ccd5eac63a4ee6d44a6ec6f8d750d35f6f8a73166c6be23fe1ad2ae749ba2edeada06cce2679dac5eee6636b591e
+  data.tar.gz: 5f7cc9072b0b180fb2f066b4caf89869e59b426dba275f2ee7431b9db99aa236b00ac799eb4ba6e1aa08a1a64c053cd5c754342c2b24805ba4323070fd641c95

data/README-2.0.0.md

@@ -2,7 +2,9 @@
 
 Version 2.0.0 is a major refactoring of ruby-jss. While attempting to provide as much backward compatibility as possible, there are some significant changes under the hood. **_PLEASE TEST YOUR CODE EXTENSIVELY_**
 
-This document discusses the high-level changes, listing the changes that have already happened, as well as planned changes and deprecations. It also provides some discussion and background around all of this. It is a work-in-progress at the moment, and will probably remain so well after initial release. Hopefully this document will prompt discussion and decision-making in the #ruby-jss channel of MacAdmins Slack (Please join us!)
+This document discusses the high-level changes, a few specific changes that have already happened, as well as planned changes and deprecations. It also provides some discussion and background around all of this. 
+
+This is a work-in-progress at the moment, and will probably remain so well after initial release. Hopefully this document will prompt discussion and decision-making in the [#ruby-jss channel of Macadmins Slack](https://macadmins.slack.com/archives/C03C7F563MK) (Please join us!)
 
 These changes have been in mind for some time, but the requirement in late 2022 for the Classic API to authenticate with Bearer Tokens from the Jamf Pro API means that the time has come, so here we are!
 
@@ -22,6 +24,7 @@ These changes have been in mind for some time, but the requirement in late 2022
       - [Which API does an object come from?](#which-api-does-an-object-come-from)
   - [Automatic code generation](#automatic-code-generation)
   - [Autoloading with Zeitwerk](#autoloading-with-zeitwerk)
+- [Known Breaking Changes](#known-breaking-changes)
 - [Notable changes from ruby-jss 1.x](#notable-changes-from-ruby-jss-1x)
   - [Paged queries to the Jamf Pro API](#paged-queries-to-the-jamf-pro-api)
   - [API data are no longer cached ?](#api-data-are-no-longer-cached-)
@@ -29,7 +32,7 @@ These changes have been in mind for some time, but the requirement in late 2022
   - [Class/Mixin hierarchy for Jamf Pro API objects](#classmixin-hierarchy-for-jamf-pro-api-objects)
   - [Support for 'Sticky Sessions' in Jamf Cloud](#support-for-sticky-sessions-in-jamf-cloud)
 - [Planned deprecations](#planned-deprecations)
-  - [Use of the term 'api' in method names, parameter names, and attributes](#use-of-the-term-api-in-method-names-parameter-names-and-attributes)
+  - [Use of the term 'api'](#use-of-the-term-api)
   - [.map_all_ids_to method for Classic API collection classes](#map_all_ids_to-method-for-classic-api-collection-classes)
   - [Using .make, #create, and #update for Classic API objects](#using-make-create-and-update-for-classic-api-objects)
   - [JSS::CONFIG](#jssconfig)
@@ -44,7 +47,7 @@ These changes have been in mind for some time, but the requirement in late 2022
 
 ## Requirements
 
-ruby-jss 2.0 requires ruby 2.6.3 or higher, and a Jamf Pro server running version 10.35 or higher.
+ruby-jss 2.0,0 requires ruby 2.6.3 or higher, and a Jamf Pro server running version 10.35 or higher.
 
 This means it will work with the OS-supplied /usr/bin/ruby in macOS 10.15 Catalina and above, until Apple removes ruby from the OS.
 
@@ -58,9 +61,9 @@ As of this writing, basic access to the API seems to be working in ruby 3, but m
 
 It looks like the biggest changes have been dealing with keyword arguments as Hashs.  Methods defined with `def methodname([...] foo = {})` need to be changed to `def methodname([...] **foo)` and calls to those methods, even in your own code, need to be changed to `methodname([...] **foo)` when `foo` is a hash of keyword args.
 
-**IMPORTANT**: do not pass raw hashes as 'keyword' args.  Instead use the double-splat: `methodname(**hash)` which should be compatible with ruby 3.x and 2.6.x
+**IMPORTANT**: This may be a breaking change. Do not pass raw hashes as 'keyword' args. Instead use the double-splat: `methodname(**hash)` which should be compatible with ruby 3.x and 2.6.x
 
-for more info see [Separation of positional and keyword arguments in Ruby 3.0](https://www.ruby-lang.org/en/news/2019/12/12/separation-of-positional-and-keyword-arguments-in-ruby-3-0/)
+For more info see [Separation of positional and keyword arguments in Ruby 3.0](https://www.ruby-lang.org/en/news/2019/12/12/separation-of-positional-and-keyword-arguments-in-ruby-3-0/)
 
 ### Combined API access
 
@@ -140,6 +143,19 @@ Then as files load, lines will be written to standard error indicating:
   - A module was mixed-in to some other module or class
   - A method was just automatically defined
 
+## Known Breaking Changes
+
+So far we've only uncovered a few areas where our ruby-jss 1.x code didn't work with ruby-jss 2.0.0
+
+- Using unsplatted Hashes as 'named parameters' to method calls. 
+  - See [Ruby 3.x support](#ruby-3x-support) above
+
+- Jamf Pro API objects no longer have aliases for their attributes
+  - See [No Attribute aliases for Jamf Pro API objects](#no-attribute-aliases-for-jamf-pro-api-objects) below
+
+- Subclassing ruby-jss classes in your own code.
+  - Those classes, and methods called on them, may need to be updated to match the new ruby-jss classes, in order to maintain _their_ backward compatibility.
+
 ## Notable changes from ruby-jss 1.x
 
 ### Paged queries to the Jamf Pro API
@@ -189,7 +205,7 @@ Give us time and we'll get everything updated. In the meantime, feel free to rea
 
 ### Support for 'Sticky Sessions' in Jamf Cloud
 
-If you are connecting to a Jamf Cloud server, you can specifcy `sticky_sessions: true` when calling `Jamf::Connection.new` or `Jamf::Connection#connect`. If you already have a connected Connection object, you can enable or disable Sticky Sessions using `my_connection_object.sticky_session =` with a boolean value (for the default connection use `Jamf.cnx.sticky_session = <boolean>`). To see the actual cookie being sent to enable sticky sessions, use `Jamf::Connection#sticky_session_cookie`. 
+If you are connecting to a Jamf Cloud server, you can specifcy `sticky_session: true` when calling `Jamf::Connection.new` or `Jamf::Connection#connect`. If you already have a connected Connection object, you can enable or disable Sticky Sessions using `my_connection_object.sticky_session =` with a boolean value (for the default connection use `Jamf.cnx.sticky_session = <boolean>`). To see the actual cookie being sent to enable sticky sessions, use `Jamf::Connection#sticky_session_cookie`. 
 
 Attempting to enable a sticky session with a connection to an on-prem server (host not ending in 'jamfcloud.com') will raise an error.
 
@@ -199,9 +215,25 @@ For details about Sticky Sessions see [Sticky Sessions for Jamf Cloud](https://d
 
 ## Planned deprecations
 
-### Use of the term 'api' in method names, parameter names, and attributes
+Even though it was publically released in 2014, ruby-jss's origins are from 2009, so it's been around for a while. We've learned a lot since then, and lots of the old lingering code is terribly out of date.
+
+The move to 2.0.0 is our opportunity to start streamlining things and cleaning up not just the code, but how it's used.
+
+We wanted to make the initial transition to 2.0.0 as backward-compatible as possible, but going forward, a lot of things will be changing or going away. 
+
+All of this is up for discussion! If you have suggestions or ideas for improvement, cleanup, or modernization, or if one of these deprecated items is important to you, [please reach out](#contact) and let us hear your thoughts.
+
+As a side effect of these planned changes, and due to our attempts to adhere to [Semantic Versioning](https://semver.org), you can expect the major version number to start going up faster than it used to.
 
-Use `cnx` instead. Example:
+Here are the things we are planning on removing or changing in the coming months-to-years:
+
+### Use of the term 'api' 
+
+In ruby-jss < 2.0, the term `api` is used with the Classic API in method names, method parameters, instance variables, attributes, and constants. It is used to pass, access, refer to, or hold instances of JSS::APIConnnection, e.g. so a method that talks to the server would use the passed connection rather than the module-wide default connection.  
+
+The term 'api' is inappropriate because the thing being passed is a 'connection' not an 'api'. Now that there are actually two APIs at play, that usage is even less appropriate.
+
+Going forward, use `cnx` (simpler to type than 'connection') instead. Example:
 
 ```ruby
 my_connection = Jamf::Connection.new 'https://user@my.jamf.server:8443/', pw: :prompt
@@ -221,10 +253,6 @@ comp = JSS::Computer.fetch id: 12, cnx: my_connection
 comp.cnx # => my_connection
 ```
 
-In ruby-jss < 2.0, the term `api` is used with the Classic API in method names, method parameters, instance variables, attributes, and constants. It is used to pass, access, refer to, or hold instances of JSS::APIConnnection, e.g. so a method that talks to the server would use the passed connection rather than the module-wide default connection.  
-
-But, the thing being passed is a 'connection' not an 'API', and now that there are actually two APIs at play, that usage is even less appropriate.
-
 The original Jamf module, which accessed only the Jamf Pro API, has always used the better-suited abbreviation `cnx` for this, and now that is standard everywhere. 
 
 For now `api` should continue to work, but it will be removed 'eventually', so please start changing your code now.
@@ -250,8 +278,6 @@ In v2.0.0 we are standardizing on the behavior of the previous Jamf module:
   - `Jamf::SomeCollectionClass#save` instance method for sending an object to the server to be created OR updated in Jamf pro.
     - Note that `#save` has been available for this use since the earliest versions of ruby-jss.
 
-
-
 This means that these deprecated methods will go away for Classic API objects
 
   - `Jamf::SomeCollectionClass.make` class method for instantiating a ruby object to be added as a new SomeCollectionClass to Jamf Pro

data/README.md

@@ -1,10 +1,25 @@
 # ruby-jss: Working with the Jamf Pro APIs in Ruby
-<a id="markdown-ruby-jss%3A-working-with-the-jamf-pro-apis-in-ruby" name="ruby-jss%3A-working-with-the-jamf-pro-apis-in-ruby"></a>
 [![Gem Version](https://badge.fury.io/rb/ruby-jss.svg)](http://badge.fury.io/rb/ruby-jss)
 
-**IMPORTANT: Known Security Issue in v1.5.3 and below**
+## Version 2.0.0 has been released
 
-Versions of ruby-jss prior to 1.6.0 contain a known security issue due to the use of the 'plist' gem.
+Version 2.0.0 has major changes! While we've strived for backward compatibility, and have done lots of testing, YMMV.  Please report any issues.
+
+### Highlights
+
+- Support for Ruby 3.x
+  - tested in 3.0 and 3.1
+- Combined access to both the Classic and Jamf Pro APIs
+  - A single namespace module
+  - Connection objects talk to both APIs & automatically handle details like bearer tokens
+- Auto-generated code for Jamf Pro API objects
+- Autoloading of code using [Zeitwerk](https://github.com/fxn/zeitwerk)
+
+For details about the changes, the document [README-2.0.0.md](README-2.0.0.md).
+
+## _IMPORTANT_: Known Security Issue in v1.5.3 and below
+
+Versions of ruby-jss prior to 1.6.0 contain a known security issue due to how we were using the 'plist' gem.
 
 This has been resolved in 1.6.0, which now uses the CFProperlyList gem.
 
@@ -15,10 +30,12 @@ Many many thanks to actae0n of Blacksun Hackers Club for reporting this issue an
 ------
 
 # Table of contents
-<a id="markdown-table-of-contents" name="table-of-contents"></a>
 
 <!-- TOC -->
 
+- [Version 2.0.0 has been released](#version-200-has-been-released)
+  - [Highlights](#highlights)
+- [_IMPORTANT_: Known Security Issue in v1.5.3 and below](#_important_-known-security-issue-in-v153-and-below)
 - [DESCRIPTION](#description)
 - [SYNOPSIS](#synopsis)
 - [USAGE](#usage)
@@ -45,7 +62,6 @@ Many many thanks to actae0n of Blacksun Hackers Club for reporting this issue an
 <!-- /TOC -->
 
 ## DESCRIPTION
-<a id="markdown-description" name="description"></a>
 
 ruby-jss defines a Ruby module called `Jamf`, which is used for accessing the 'Classic' and 
 'Jamf Pro' APIs of a Jamf Pro server. Jamf Pro is an enterprise-level management tool for Apple
@@ -69,7 +85,6 @@ Hopefully others will find it useful, and add more to it as well.
 [Full technical documentation can be found here.](http://www.rubydoc.info/gems/ruby-jss/)
 
 ## SYNOPSIS
-<a id="markdown-synopsis" name="synopsis"></a>
 
 Here are some simple examples of using ruby-jss
 
@@ -116,10 +131,8 @@ ns.save
 ```
 
 ## USAGE
-<a id="markdown-usage" name="usage"></a>
 
 ### Connecting to the Server
-<a id="markdown-connecting-to-the-server" name="connecting-to-the-server"></a>
 
 Before you can work with Jamf Pros Objects via the APIs, you have to connect to the server.
 
@@ -154,7 +167,6 @@ Also see Jamf::Configuration, and the [CONFIGURATION](#configuration) section be
 server connection parameters in a simple config file.
 
 #### Using multiple connections
-<a id="markdown-using-multiple-connections" name="using-multiple-connections"></a>
 
 Most of the time, you'll only need a single connection to a single server, and the default connection will be sufficient. However 
 you can also create multiple Connection objects, to different servers, or perhaps the same server with different credentials and 
@@ -179,7 +191,6 @@ common_ipr_sns = ipr_sns_1 & ipr_sns_2
 ```
 
 ### Working with Jamf Objects
-<a id="markdown-working-with-jamf-objects" name="working-with-jamf-objects"></a>
 
 All of the ruby classes representing objects in Jamf Pro have common methods for creating, listing, retrieving, updating, and deleting via the API. 
 All supported objects can be listed, retrieved and deleted, but only some can be updated or created, mostly becase we haven't needed to do that ourselves
@@ -193,7 +204,6 @@ as are the API resources for accessing management history.
 --------
 
 #### Listing Objects
-<a id="markdown-listing-objects" name="listing-objects"></a>
 
 To get an Array with a summary of every object in the Jamf of some Class, call that Class's .all method:
 
@@ -218,7 +228,6 @@ To create, modify, or perform advanced searches, use the classes Jamf::AdvancedC
 --------
 
 #### Retrieving Objects
-<a id="markdown-retrieving-objects" name="retrieving-objects"></a>
 
 To retrieve a single object call the class's `.fetch` method and provide a name:,  id:, or other valid identifier.
 
@@ -234,7 +243,6 @@ You can even fetch objects without specifying the kind of identifier, e.g. `Jamf
 --------
 
 #### Creating Objects
-<a id="markdown-creating-objects" name="creating-objects"></a>
 
 Some Objects can be created anew in the Jamf via ruby. To do so, first make a Ruby object using the class's `.create` method and providing a unique :name:, e.g.
 
@@ -260,7 +268,6 @@ new_pkg.save # returns 453, the id number of the object just created
 --------
 
 #### Updating Objects
-<a id="markdown-updating-objects" name="updating-objects"></a>
 
 Some objects can be modified.
 
@@ -278,7 +285,6 @@ existing_script.save #  => returns the id number of the object just saved
 --------
 
 #### Deleting Objects
-<a id="markdown-deleting-objects" name="deleting-objects"></a>
 
 To delete an object, just call its #delete method
 
@@ -300,7 +306,6 @@ For more details see the docs for:
 See the individual subclasses for any details specific to them.
 
 ## OBJECTS IMPLEMENTED
-<a id="markdown-objects-implemented" name="objects-implemented"></a>
 
 While the API itself supports nearly full CRUD (Create,Read,Update,Delete) for all objects, ruby-jss doesn't yet do so. Why? Because implementing the data validation and other parts needed for creating & updating can be time-consuming and we've focused on what we needed. As we keep developing ruby-jss, this list changes. If you'd like to help implement some of these objects more fully, please fork the github project and reach out to us at ruby-jss@pixar.com.
 
@@ -352,7 +357,6 @@ Here's some of what we've implemented so far. See each Class's [documentation(ht
 **NOTE** Most Computer and MobileDevice data gathered by an Inventory Upate (a.k.a. 'recon') is not editable.
 
 #### Other useful classes & modules:
-<a id="markdown-other-useful-classes-%26-modules%3A" name="other-useful-classes-%26-modules%3A"></a>
 
 These modules either provide stand-alone methods, or are mixed in to other classes to extend their functionality. See their documentation for details
 
@@ -365,7 +369,6 @@ These modules either provide stand-alone methods, or are mixed in to other class
 * {Jamf::MDM} - a module that handles sending MDM commands. It is accessed via the Computer and MobileDevice classes and their instances.
 
 ## Object-related API endpoints
-<a id="markdown-object-related-api-endpoints" name="object-related-api-endpoints"></a>
 
 The classic API provides many endpoints not just for objects stored in Jamf Pro, but also for accessing data *about* those  objects or interacting with the machines they represent. ruby-jss embeds access to those endpoints into their related classes.
 
@@ -379,7 +382,6 @@ For example:
   - These endpoints provide access to the MDM infrastructure, and can be used to send MDM commands. Ruby-jss provides these as class and instance methods in {Jamf::Computer}, {Jamf::ComputerGroup}, {Jamf::MobileDevice}, and {Jamf::MobileDeviceGroup}
 
 ## CONFIGURATION
-<a id="markdown-configuration" name="configuration"></a>
 
 The {Jamf::Configuration} singleton class is used to read, write, and use site-specific defaults for the Jamf module. When ruby-jss is required, the single instance of {Jamf::Configuration} is created and accessible via the `Jamf.config` method. At that time the system-wide file /etc/ruby-jss.conf is examined if it exists, and the items in it are loaded into the attributes of Configuration instance. The user-specific file ~/.ruby-jss.conf then is examined if it exists, and any items defined there will override those values from the system-wide file.
 
@@ -411,7 +413,6 @@ api_timeout: 90
 and then any calls to Jamf.cnx.connect will assume that server and username, and use a timeout of 90 seconds.
 
 ### Passwords
-<a id="markdown-passwords" name="passwords"></a>
 
 The config files don't store passwords and the {Jamf::Configuration} instance doesn't work with them. You'll have to use your own methods for acquiring the password for the Jamf.cnx.connect call.
 
@@ -435,7 +436,6 @@ Jamf.cnx.connect pw: password   # other arguments used from the config settings
 ```
 
 ## BEYOND THE API
-<a id="markdown-beyond-the-api" name="beyond-the-api"></a>
 
 While the Jamf Pro APIs provide access to object data in the Jamf, ruby-jss tries to use that data to provide more than just information exchange. Here are some examples of how ruby-jss uses the API to provide functionality found in various Jamf tools:
 
@@ -456,14 +456,12 @@ While the Jamf Pro APIs provide access to object data in the Jamf, ruby-jss trie
   * {Jamf::ExtensionAttribute} work with {Jamf::AdvancedSearch} subclasses to provide extra reporting about Extension Attribute values.
 
 ## INSTALL
-<a id="markdown-install" name="install"></a>
 
 In general, you can install ruby-jss with this command:
 
 `gem install ruby-jss`
 
 ## REQUIREMENTS
-<a id="markdown-requirements" name="requirements"></a>
 
 ruby-jss 2.0.0 requires:
 
@@ -475,7 +473,6 @@ See the .gemspec file for details
 
 
 ### Contact
-<a id="markdown-contact" name="contact"></a>
 
 If you have questions or feedback about ruby-jss, please reach out  to us via:
 - The [#ruby-jss channel of Macadmins Slack](https://macadmins.slack.com/archives/C03C7F563MK)
@@ -484,7 +481,6 @@ If you have questions or feedback about ruby-jss, please reach out  to us via:
 
 
 ## HELP & CONTACT INFO
-<a id="markdown-help-%26-contact-info" name="help-%26-contact-info"></a>
 
 Full documentation is available at [rubydoc.info](http://www.rubydoc.info/gems/ruby-jss/).
 
@@ -496,7 +492,6 @@ You can report issues in several ways:
 - Join the conversation in the [#ruby-jss Macadmins Slack Channel](https://macadmins.slack.com/archives/C03C7F563MK)
 
 ## LICENSE
-<a id="markdown-license" name="license"></a>
 
 Copyright 2022 Pixar
 

data/lib/jamf/version.rb

@@ -27,6 +27,6 @@
 module Jamf
 
   ### The version of ruby-jss
-  VERSION = '2.0.0b5'.freeze
+  VERSION = '2.0.0rc1'.freeze
 
 end # module

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-jss
 version: !ruby/object:Gem::Version
-  version: 2.0.0b5
+  version: 2.0.0rc1
 platform: ruby
 authors:
 - Chris Lasell
@@ -10,7 +10,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-09-06 00:00:00.000000000 Z
+date: 2022-09-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: CFPropertyList