Closes #2141 Superseded derive_param_extreme_record()

[ddsjoberg]

Thank you for your Pull Request! We have developed this task checklist from the Development Process Guide to help with the final steps of the process. Completing the below tasks helps to ensure our reviewers can maximize their time on your code as well as making sure the admiral codebase remains robust and consistent.

Please check off each taskbox as an acknowledgment that you completed the task or check off that it is not relevant to your Pull Request. This checklist is part of the Github Action workflows and the Pull Request will not be merged into the devel branch until you have checked off each task.

• Place Closes General Issue: Supersede derive_param_extreme_record() #2141 into the beginning of your Pull Request Title (Use Edit button in top-right if you need to update)
• Code is formatted according to the tidyverse style guide. Run styler::style_file() to style R and Rmd files
• Updated relevant unit tests or have written new unit tests, which should consider realistic data scenarios and edge cases, e.g. empty datasets, errors, boundary cases etc. - See Unit Test Guide
• If you removed/replaced any function and/or function parameters, did you fully follow the deprecation guidance?
• Update to all relevant roxygen headers and examples, including keywords and families. Refer to the categorization of functions to tag appropriate keyword/family.
• Run devtools::document() so all .Rd files in the man folder and the NAMESPACE file in the project root are updated appropriately
• Address any updates needed for vignettes and/or templates
• Update NEWS.md under the header # admiral (development version) if the changes pertain to a user-facing function (i.e. it has an @export tag) or documentation aimed at users (rather than developers)
• Build admiral site pkgdown::build_site() and check that all affected examples are displayed correctly and that all new functions occur on the "Reference" page.
• Address or fix all lintr warnings and errors - lintr::lint_package()
• Run R CMD check locally and address all errors and warnings - devtools::check()
• Link the issue in the Development Section on the right hand side.
• Address all merge conflicts and resolve appropriately
• Pat yourself on the back for a job well done! Much love to your accomplishment!

[ddsjoberg]

FYI I added #' @keyword internal so the function would not appear on the Reference page on the pgkdown site. No need to use space advertising a function we no longer support as the best solution on the already large page of functions.

[github-actions]

Package	Line Rate	Health
admiral	98%	✔
Summary	98% (4404 / 4473)	✔

[bundfussr]

Could you add the superseded badge and a reference to derive_extreme_event() to the description of derive_param_extreme_record()?

[bundfussr]

I think @keywords superseded should be used and a "Superseded" section should be added to the "Reference" page. Superseded functions could be used in submissions. If the health authority looks at the admiral webpage and can't find the function, it looks bad.

@bms63 , @manciniedoardo , do you agree?

[manciniedoardo]

Yes, completely agree. Our discussion around "superseded" mentioned that we want to allow users to still use the functions, even if we'd _encourage them to use whatever new function came after.

[ddsjoberg]

The help page still appears on the website and is easily found by searching the website. This will waste space on the already large Reference page.

Regardless, please feel free to update as you'd like.

[bms63]

I think a "superseded" section is a good call on the reference page.

Hopefully, less deprecations will be occurring so will gain back some real estate. I think we should also remove some of the other sections that users won't really care about

[zdz2101]

I thought the testthat page mightve needed updates for messaging but I suppose superseding is just messaging without warning/errors?

[bms63]

Is it okay if I implement this superseded section in this PR or do we want to do it in another PR? I like how dplyr does it

[ddsjoberg]

@bms63 feel free to implement anything you'd like in this PR branch.

I think the key difference between that Superseded section and ours is that those functions (spread(), gather()) have been used millions and millions of times, compared to ours with very few users in production.

[bms63]

@bms63 feel free to implement anything you'd like in this PR branch.

I think the key difference between that Superseded section and ours is that those functions (spread(), gather()) have been used millions and millions of times, compared to ours with very few users in production.

Okay. I recognize that we aren't at the level of dplyr - lol. It was just an example of something I thought was handy in a pkgdown site

Going to implement to help keep track. The deprecation section was nice for me and I believe other devs to kick things out of admiral. Also never really agreed on how long something stays superseded and if we remove the old function after a certain amount of time.

[ddsjoberg]

Also never really agreed on how long something stays superseded and if we remove the old function after a certain amount of time.

@bms63 if we plan to remove a function in the future, it should be deprecated rather than superseded.

[bms63]

Also never really agreed on how long something stays superseded and if we remove the old function after a certain amount of time.

@bms63 if we plan to remove a function in the future, it should be deprecated rather than superseded.

ah okay. So a superseded function will stay around forever then. im fine with that. I was thinking after 4 years or so we might want to eject it...but im glad to follow whatever the lifecycle recommendations are.

[ddsjoberg]

@bms63 I heard Hadley once jokingly say something to the effect that developers may want to consider using Superseded functions over other exported functions, because they've committed to 1. Keeping it around forever, and 2. Committed to not develop it further (because they have already released a better way of completing the same task), so its API should never change.

[manciniedoardo]

@bms63 I heard Hadley once jokingly say something to the effect that developers may want to consider using Superseded functions over other exported functions, because they've committed to 1. Keeping it around forever, and 2. Committed to not develop it further (because they have already released a better way of completing the same task), so its API should never change.

@ddsjoberg that's hilarious, let's hope our users don't catch on to this 😆

[bms63]

I made my little superseded section. I am happy :) Anyone unhappy?