Conceptualizing a Future 3.0.0 release

[nutterb]

We've had a few passing comments now about some potentially breaking changes. As I've been working on things I've been taking notes on things in the package that could be part of a breaking change release.

• exportRecords
  • Two options
    • Retire complete
    • Replace with a new interface that matches the default settings of the API method (would effectively return raw data)
  • Remove checkbox_suffixes
  • Remove fieldToVar
  • Remove syncUnderscoreCodings (This hasn't been an issue since REDCap 5.5.21, I think we can safely cut it by now)
• exportReports
  • Two options
    • Retire completely
    • Replace with a new interface that matches the default settings of the API method (would effectively return raw data)
  • We will need an exportReportsTyped before this can be done. I'll log an issue for that soon.
• importRecords
  • Replace internals to use castForImport to prep data for import
  • Remove validateImport
  • Remove validateImport_methods
• redcapFactors
  • Remove Extraction.R
  • Remove makeRedcapFactor.R
  • recodeCheck.R needs to be stripped of efforts to reapply redcapFactor attributes
  • remove RedcapFactorFlip
• Remove exportProjectInfo
• Remove exportBundle
• Remove massert (we could actually do this at any time. We've already remove all uses of it)
• Remove cleanseMetaData (this was an ill-advised attempt to strip the meta data of unicode characters. I think we have better tools for that now)

If you want to pursue any/all of these, we may want to pick out a target date for the 3.0.0 release and add it to the package startup message with something like:

A future release of redcapAPI 3.0.0 will introduce several breaking changes
* The `exportRecords` function interface will be replaced. Please switch your processes to `exportRecordsTyped`
* The `exportReports` function interface will be replaced. Please switch your processes to `exportReportsTyped`
* The `importRecords` function interface will be replaced to utilize `castForImport` to prepare data for import. 
* The `redcapFactor` class is being discontinued with all its supporting methods (including `redcapFactorFlip`)
* The `exportProjectInfo` and `exportBundle` functions are being discontinued. Their functionality is replaced by caching values on the connection object.

[spgarbet]

We going to start preparing a 2.7.x training seminar in late July. I like the road map you've outlined here and in general I lean towards deleting things we deprecated. At some point what we decide to remove should get louder with it's complaints.

I did see some code today that was a couple pages from a few years back, that under the rewrite is about 8 lines. This is very encouraging.

[nutterb]

Checklist to help me keep track of all of the things I need to do to get this over the finish line

Deprecation messages

(I will do these first so that they can be available whenever we decide to push them)

• Update NEWS
• package startup message
• exportRecords message
• exportReports message
• importRecords message
• exportBundle message
• exportProjectInfo message
• redcapFactorFlip message
• cleanseMetaData message
• recodeCheck message

Nothing below here has any interaction elsewhere in the package. Once developed, it can sit until we're ready publish it.

Functions to rewrite

• exportRecords
• exportRecords.offlineConnection (_chose not to do this, as the REDCap UI can produce the file using all of the options. There's no real point in providing this if we aren't providing any casting beyond what the API provides)
• exportReports
• importRecords

Functions/files to delete

• checkbox_suffixes
• fieldToVar
• syncUnderscoreCodings
• validateImport
• validateImport_methods
• Extraction
• makeRedcapFactor
• recodeCheck
• redcapFactorFlip
• exportProjectInfo
• exportBundle
• massert
• cleansMetaData

[nutterb]

The branch https://github.com/vubiostat/redcapAPI/tree/issue-113-deprecation-notices is ready with the deprecation notices whenever you want to tie them in.

[nutterb]

The branch https://github.com/vubiostat/redcapAPI/tree/issue-113-version-3.0.0 has the designated changes.

We'll want to keep it up to date, but it is ready to become 3.0.0

[spgarbet]

We've hit 3.0.0 already? Maybe we target this for a CRAN release.

[nutterb]

I'm not sure we want to push 3.0.0 to CRAN just yet. Not because the work isn't done, but because it does have a number of breaking changes. We may want to push 2.8.0 to CRAN first (with all of the deprecation notices) and give a time frame on when 3.0.0 will get pushed out.

I'm not sure what the courtesy period is before pushing a change like this. But I'm thinking "over night with no warning" is a little short. :)

[spgarbet]

Ah, this is the breaking set.