This outlines how to propose a change to the admiral package. For more detailed info about contributing to {admiral}, and other pharmaverse packages, please see the Contribution Guide as well as other Developer Guides in the Articles section of the {admiraldev} website.
Please note that we try to align to best practices used in other R packages' development processes - so veteran developers should be familiar with our processes. However, we do deviate slightly from some best practices and we advise all new contributors to review our package documentation accordingly.
🦋 For each new contribution, the user creates an issue on the issue tab on GitHub to put it in our backlog. The issues can range from bug identification and/or fixes, enhancements to functions, documentation, tests or new features.
🦋 We advise you to contact us when an issue is created via Slack (If you don't have access, use this link to join). We can discuss details or align expectations if you are not familiar with the {admiral}
philosophy and programming strategy. The team will try to review the issues within the next backlog meeting and give some initial feedback. Since we are not a 100% fully resourced software development team it might be that some issues will take longer to respond to depending on the amount of overall issues.
🦋 We advise you to familiarize yourself with our programming strategy, guidance for GitHub usage and unit testing.
🦋 All newly created issues will be reviewed within the next backlog meeting and the creator will receive an initial feedback via a comment. Someone from the core development team will then triage new issues by assigning the appropriate labels (such as “user request” so we can easily identify new requests).
🦋 Issues are meant to be taken on by users from the Pharma programming community and not exclusively by the {admiral}
team from GSK and Roche.
🦋 User creates an issue and ideally contacts an {admiral}
team member via Slack.
🦋 The {admiral}
core development team will contact the issue creator as soon as possible to discuss further details.
🦋 First, the user creates an issue or comments on an existing issue to notify that they’d like to contribute code.
🦋 Follow our development process step-by-step guide.
🦋 We advise to contact an {admiral}
core development team directly via Slack before submitting code for complex functionality.
If you decide to contribute with code and you're ready to make your first code contribution, this detailed development process step-by-step guide will help tie all the other detailed vignettes together to give you the simplest experience of helping to grow and enhance our codebase.
- Create a new feature branch from the
main
branch following the naming convention and pull the latest changes - as detailed on the GitHub usage guide. - Familiarize yourself with the
{admiral}
programming strategy, and then make the required code updates. - Before making a pull request, check the Pull Request Review
Guidance & the following checklist of
common things developers miss:
a. Is all your code formatted according to the
tidyverse style guide?
b. Did you create/add appropriate unit
tests?
c. If you removed/replaced any function and/or function parameters,
did you fully follow the deprecation
guidance?
d. Did you update the
[documentation]https://pharmaverse.github.io/admiraldev/articles/programming_strategy.html#function-header-documentation)?
If so, remember to run
devtools::document()
and include the updatedNAMESPACE
and.Rd
files inman/
. e. Does your code update have any impact on the ADaM template R scripts stored ininst/templates
? f. Does your code update have any impact on the vignettes stored in vignettes? g. Did you update the ChangelogNEWS.md
? h. Did you build{admiral}
sitepkgdown::build_site()
and check that all affected examples are displayed correctly and that all new functions occur on the "Reference" page? - Once happy with all the updates, make a pull
request to merge to the
main
branch and link the issue so that it closes after successful merging. - Check that there are no merge conflicts. If there are any, fix them before requesting review. See solving merge conflicts guidance.
- Check the results of the automated
R-CMD check
andlintr
checks and if any issues consult this guide. - Assign a reviewer from the
{admiral}
core development team - this could be anyone you discussed the issue with previously via Slack or GitHub. If unsure, add a comment that the pull request is ready for review and add the@pharmaverse/admiral
tag to it. - Once the review is completed, the reviewer will merge the PR and this will then automatically delete the feature branch.
Finally, just a note to say from the core developers that we hugely
appreciate you taking the time to contribute to {admiral}
. Don't be
offended if during review we send requests back to you, as the
expectations are high so that we can ensure the {admiral}
codebase
remains robust and consistent. The best way to learn here is always to
jump in and get involved, so please don't be afraid you'll make mistakes
along the way -- we all have and continue to do so, and that's what the
reviews are for. Also if ever you get stuck don't hesitate to reach out
for support via the Slack
channel.
Welcome to our {admiral}
community!