usethis::create_package("mypackage").DESCRIPTION file should define:Package:
Title:
Description:
Version:
Authors@R:
role = "cre" for the maintainer,
role = "aut" for substantial authorship, and
role = "ctb" for smaller contributions.
License:
Depends:
R (>= 4.0.0)
Imports:
Suggests:
RoxygenNote: 8.0.0
Encoding: UTF-8
Language: en-GB`
Use of roxygen2 is recommended for documentation so that NAMESPACE and man/ Files are generated automatically.
Functions should be stored in the R folders and tests in the tests folder.
The inst/ directory must include the "DATASHIELD" configuration files specifying the assign methods, aggregate methods, and package options. (see https://github.com/datashield/dsBase/blob/v6.3.6-dev/inst/DATASHIELD for example)
Create a README template with: usethis::use_readme_rmd(). The README should include basic details like:
Every package could have an explicit licence. The licence field must also be correct in DESCRIPTION.
Packages are expected to complete devtools::check() without errors. Testing across Linux, macOS, and Windows is encouraged to identify platform-specific issues and help maintain reliable behaviour across the environments used by the DataSHIELD community.
Package-level documentation can be created with usethis::use_package_doc(). This creates a package documentation file, usually: R/mypackage-package.R. Use it to describe the package’s overall purpose and main workflows.
A citation file could be included when the package supports published research, has a citable method, or should be referenced in academic work. usethis::use_citation(). This creates: inst/CITATION .
Consider including at least one vignette when the package needs a worked example or workflow explanation. Use: usethis::use_vignette("getting-started") .
If including Logo, it could be stored in: man/figures/logo.png.
DataSHIELD packages follow camel case naming conventions. Client packages should use the suffix Client.
Function names in server and client-side packages follow camelCase naming , DS is used as a suffix in server-side and ds. as prefix in client-side packages.
Examples:
| Server package | Client package | |
|---|---|---|
dsBase |
dsBaseClient |
|
asListDS |
ds.asList |
Function names |
Using version control is recommended for DataSHIELD package development to provide a traceable history of changes, support collaborative development, and make it easier to review or revert modifications. While several version-control systems are available, Git is recommended because it is free, open source, widely adopted in R development, and integrates well with collaborative platforms such as GitHub.
Packages in development when in GitHub are indicated by "-dev" at end of branch name, and with addition of .9000 to end of R package version.
Recommended repository practices:
- Use Git from the start of package development
- Host repositories on GitHub (preferred)
- Use `main` as the default branch name, stable development branch
- Use "-dev" at end of branch name when in development
- Commit changes frequently with meaningful commit messages
- Use pull requests for reviewing changes before merging
DataSHIELD packages should follow the standard tidyverse-style versioning convention: <major>.<minor>.<patch> . The version number should be updated in the DESCRIPTION file.
The first stable and shareable release should normally be version 0.1.0. This indicates that the package is functional, tested, and suitable for use by collaborators, while still allowing for minor improvements based on early user feedback.
Version 1.0.0 should be reserved for the first production-ready release, where the package is considered complete, stable, and ready for general use.
During active development, append the suffix .9000 to the package version (e.g., 0.1.0.9000) to indicate that the package is under development and not yet a stable release.
Development branches should use the suffix -dev (e.g., feature-name-dev) to clearly distinguish them from release branches.
Where possible, keep the client-side and server-side package versions aligned. This may occasionally require releasing a package with no functional changes so that both packages remain on the same version.
Packages should maintain a NEWS.md file documenting changes between versions.
Recommended contents:
- New features
- Bug fixes
- Breaking changes
- Deprecated functions
- Documentation improvements
At a minimum, contributors associated with a feature or bug fix should be acknowledged near the corresponding entry where appropriate.
Git tags for releases: Each package release should be associated with a Git tag.
Release workflow recommendations: A typical release workflow should include:
1. Update package version in DESCRIPTION
2. Update NEWS.md
3. Run package checks
* devtools::check()
* R CMD check
4. Run tests
* testthat::test_dir()
* CI pipeline
5. Run linting/style checks (optional but recommended)
* lintr
* styler
5. Commit release changes
6. Push commits and tags to remote repository (main)
7. Submit to CRAN
8. After CRAN accepts, merge the main to production branch
9. Create git tag.
- I think "Recommended basic structure", got server-side packages, needs to include
instdirectoryinstdirectory needs to include DataSHIELD file to specify Assign and Aggregate method also Options- Wouldn't first stable release be
1.0.0- When possible try keep client-side and server-side package versions the same. The may require release of "no change" packages.
- Current conventaion is that packages in development when in GitHub are indicated by "-dev" at end of branch name, and with addition of
.9000to end of R package version.Stuart 2027-07-22