Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

CRAN release & adonis deprecation: Request for Comments #523

Open
jarioksa opened this issue Aug 8, 2022 · 11 comments
Open

CRAN release & adonis deprecation: Request for Comments #523

jarioksa opened this issue Aug 8, 2022 · 11 comments

Comments

@jarioksa
Copy link
Contributor

jarioksa commented Aug 8, 2022

I am planning a new CRAN release of vegan in the latter half of August. There are quite a few changes, although nothing very dramatic. For most users the main thing may be wider and robuster support for tidy dialect and ggplot graphics. See NEWS for details of the numerous other changes.

For release the main thing may be that I had planned to deprecate adonis in favour of adonis2 in this release. adonis2 was released in vegan 2.4-0 on Jun-15 2016 or more than six years ago, but it seems that most dependent packages still use adonis. I ran reverse dependence tests, and found out that six packages will issue a WARNING if adonis is deprecated: betaper, GUniFrac, microbial, RVAideMemoire, SigTree and smartsnp. In addition, QFASA passes tests without WARNING, but uses adonis without explicit import as vegan::adonis(). Similar test is performed in CRAN and new WARNINGs are flagged as changes to "worse", and may cause ripples in the smooth submission process. Therefore I'd like to avoid those changes to "worse". I planned to deprecate adonis already in the current release 2.6-2, but just to avoid problems I changed warning() to message("'adonis' will be deprecated: use 'adonis2' instead") which is not flagged in the CRAN process. I also emailed to those package authors on 15-Apr 2022. My dependence tests were less complete then, and did not include many packages dependent on BioConductor, and I only found five "worse" cases. Two of these were fixed promptly (dispRity and microeco), but three are still in the current list of regressions.

I'm still uncertain what to do or what should be the deprecation policy. My initial plan was just to phase out and remove adonis and leave only adonis2. However, dispRity defines an S3 method for adonis (and correctly handles adonis2), and obviously prefers to keep the name. One choice is to keep the name adonis in vegan, but eventually synonymize it with adonis2. The API is similar in both and if the function is just used via vegan API, users should see no difference (adonis2 offers more choices, but default is similar as old adonis). However, if packages try to access the internal structures of the result object, they will fail because intestines of adonis and adonis2 are completely different.

One way to proceed is:

  1. Keep the 2.6-2 behaviour in the next release: print message() of future deprecation, but run adonis.
  2. In a future release, print message, but run adonis2. That is, to remove adonis code and make commands adonis and adonis2 synonyms. This will give an error if there is a package that tries to access internals of the result object, but normal use should see no difference.

I just wonder, if there should be one release in between with warning to alert those package authors that access the adonis2 result object directly.

CC: @cstewartGH @ChristianHuber @TGuillerme @ChiLiubio

@TGuillerme
Copy link

Thanks for the heads up @jarioksa! I'm happy to go with either option (i.e. the release in between with warning or the straight synonymy). I'm also happy to change the S3 in dispRity to .adonis2 if that helps (I kept it as .adonis since I imagine people are familiar with that function name - but I might be wrong). I'm going to publish a release (1.7) this week so I can quickly add the change before it goes to CRAN.

@cstewartGH
Copy link

cstewartGH commented Aug 17, 2022 via email

jarioksa added a commit that referenced this issue Sep 28, 2022
Discussed in github issue #523. Step 1 is to keep here 2.6-2
behaviour and print a message.
@gavinsimpson
Copy link
Contributor

I've done a PR on QFASA to add an importFrom(vegan, adonis) statement: cstewartGH/QFASA#13 But I assume this isn't a major problem other than the fact that it still uses adonis() and @jarioksa you wanted to throw deprecation messages that would complicated getting this on CRAN?

I think a recent commit (23f6833) from you @jarioksa has loosened the deprecation warnings to just a message. So I assume you are going with something like your wondering "if there should be one release in between with warning to alert those package authors that access the adonis result object directly."

My personal opinion would be that we eventually make adonis() defunct (so we must deprecate it first) - I want old code to error rather than silently (or otherwise) return a different object if the version of vegan I am using has changed that much.

I appreciate this will cause some CRAN headaches but so long as we follow the approved route of contacting maintainers, then deprecating adonis() officially for a point release before making it defunct in a later point release, the problem will become that of other package maintainers to either update their code to use adonis2() or find some other solution.

@cstewartGH
Copy link

Thank you for this! I have updated the QFASA package with adonis2() (which required a few changes to my code) but I am still in the process of making other changes to the package and haven't submitted it to CRAN yet.

jarioksa added a commit that referenced this issue Oct 11, 2022
The failing packages still using adonis after release of adonis2 on
June 15, 2016 (vegan 2.4-0) are betaper, GUniFrac, microbial,
RVAideMemoire, SigTree and smartsnp.
@jarioksa
Copy link
Contributor Author

jarioksa commented Oct 11, 2022

vegan 2.6-4 is now on CRAN. It will extend the mercy period and only print a message of future adonis deprecation. That deprecation will happen when the current devel version (2.6-5) will be released. The following packages still use adonis according to reverse dependency tests: betaper, GUniFrac, microbial, RVAideMemoire, SigTree, smartsnp.

@christianangulo450
Copy link

Hello, dear friends. I would like to know how I can get the pdf. file to learn how to use vegan.

@jarioksa
Copy link
Contributor Author

I am about to publish next version of vegan (finally) with deprecation of adonis. Reverse dependence tests still found five packages that call adonis.

RVAideMemoire is actively maintained, and one of its core functions switched to adonis2. There is still one function to call adonis, but the issue looks easy to handle, and I have emailed the maintainer with suggestions.

Packages betaper, microbial, SigTree and smartsnp have not been fixed. I emailed to maintainers in 2022, but none of them answered. The latest CRAN versions of these are from 2017 to 2021, and the packages may be forgotten and unmaintained. I'll mail these maintainers again, but I do not expect responses now (I did not get any responses in 2022).

I have not looked at the source code of these four packages, and I do not know how adonis is used there and how simple the fixes can be. I do not see much reason to check this if I cannot reach the maintainer. I did look at the RVAideMemoire code because it had more recent versions and the maintainer could be reached.

@jarioksa
Copy link
Contributor Author

adonis was deprecated in CRAN release 2.6-6 and is defunct in github version 2.7-0. This breaks some CRAN packages. Issue #647 monitors the breaking packages, and Announcement #641 gives instructions of adapting your packages and scripts to the changes.

@cstewartGH
Copy link

cstewartGH commented Nov 21, 2024 via email

@jarioksa
Copy link
Contributor Author

@cstewartGH , yes I know your package is OK. I was closing some old and solved issues, and github automatically sent messages to people involved in those issues. This was an unfortunate flashback. My apologies.

@cstewartGH
Copy link

cstewartGH commented Nov 22, 2024 via email

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

5 participants