Developer Code Contributing Guidelines

[donyunardi]

Summary

In order to ensure quality and consistency in our documentation, it would be beneficial to establish some guidelines when contributing code or functions to our products. By doing so, we can empower code contributors to contribute effectively.

Related with findings in insightsengineering/teal.widgets#148 (comment)

Several examples of guidelines

• Centralize import and importFrom statements in the package.R file instead of in each function file.
  • https://r-pkgs.org/man.html#sec-man-package-doc
• Include a title and a description in the roxygen notes for every function.
• Exported functions and objects should have an @example section.
  • If it is wrapped in a \dontrun{}, the example should still be runnable interactively.
• The appropriate scenario to use import, importFrom, or :: when writing functions.

Tasks

• Discuss with team
• Run a PoC
  • Create a set of guidance that we can follow
  • Implement to one package and assess
• Documentation fixes teal#818
• Revise Documentation teal.widgets#149
• Documentation fixes teal.transform#128
• Finalize guidelines
• Make it public

[pawelru]

This should be included in the contributor guidelines - example. This file is mass-propagated from the r.pkg.template therefore it should not be a repo-specific. If you want to make any changes - please push it there and ask IDR to help with mass-propagation.

[pawelru]

hey @donyunardi can you please update me with the status of this. Can we close it?

[donyunardi]

I don't think we can close this yet because we haven't decided which content we should make public and how we should present it.

I do think we have enough content and agreement based on these past issues:

• https://github.com/insightsengineering/coredev-tasks/issues/512
• Pre-release activities teal.reporter#237
• Pre-release activities teal.modules.general#624