repo-best-practices

From an R Dev Day issue, we are collating best-practices to apply to r-devel repos.

At the moment, we are gathering ideas on best practices.

See also GitHub's guide to repo best practices

Essential best practices (advised for all r-devel repos)

• README.md
  • Include example of how to use the project.
  • Comments should include break down of code describing function and method responsibility.
• CONTRIBUTING.md
  • Decribe process for code review for developers to review changes.
  • Create one for the r-devel org as a whole - see #1
• LICENSE.md
  • Make sure this is appropriate for the repo (see https://choosealicense.com/)
    • (Could consider making recommendations for different project types)
• .gitignore
  • A standard .gitignore including basics for R & quarto
• CODE_OF_CONDUCT.md
  • Create one for the r-devel org as a whole - see #2
• CODEOWNERS file
• Securing the repo
  • Dependabot alerts
  • Secret scanning
  • Protect main branch (disallow non-maintainers to push to, or delete main branch)¹²
  • Code scanning¹² See GitHub's guide to repo best practices and GitHub's security Quickstart guide for more details
• Website or homepage URL

Advisable best practices (nice to have at maintainer's discretion)

• Issue and PR templates
• Issue labels
• All Contributors - rOpenSci have developed an R package called {allcontributors}
• CITATION.cff
• Branch protection (admins/maintainers can bypass)²
  • Disallow pushing to or deleting main branch
  • Require at least one approving review of PRs from a CODEOWNER
  • Require linear history (squash/rebase)
  • Disallow force pushes
• Repository topics

Repo-specific considerations

Quarto projects

• Use GHA for publishing
• Check accessibility with the wave tool
  via their browser extensions
  • Alt-text for all images
  • Colour contrast requirements
  • Note that there are some issues with Quarto sites revealed by wave that will need raising with Quarto
• Encourage engagement and contribution with repository links

website:
  repo-url: https://github.com/r-devel/YOUR-REPO
  repo-actions: [edit, issue]

• Consider "editions" of books (with changes tracked in a CHANGELOG.md or NEWS.md)
  • Look at other community books (e.g. The Turing Way) to see how they handle this

Software Projects

• Document changes by version number in CHANGELOG.md or NEWS.md
• Create GitHub releases for new versions
• Use semantic versioning
• Release strategy, e.g. semantic versioning, release notes, deployment process

Further considerations

• pre-commit hooks using the {precommit} package
  • Which would be useful for which type of project?

Footnotes

1. Enforced by applying rulesets/protect_main_branch_essential.json ↩ ↩²

2. Enforced by applying rulesets/protect_main_branch_advised.json ↩ ↩² ↩³