Contributing to BioCro

[GitHub issues]: https://github.com/biocro/biocro/issues "Doxygen documentation" {target="_blank"}

    "Code dependencies are the devil" {target="_blank"}
    "Our Software Dependency Problem" {target="_blank"}
    "Standard Library Compatibility" {target="_blank"}

[Boost FAQ]: https://www.boost.org/users/faq.html "The Boost FAQ" {target="_blank"} [CRAN policies]: https://cran.r-project.org/web/packages/policies.html "CRAN Repository Policy" {target="_blank"} [renv]: https://rstudio.github.io/renv/ "The renv package" {target="_blank"} "Docker and Reproducibility" {target="_blank"} "Reproducible analysis and Research Transparency" {target="_blank"} "Advanced R (1e) style guide" {target="_blank"}

[Solar Position module]: r params$biocro_root/src/module_library/solar_position_michalsky.h "Source code for the Solar Position module" {target="_blank"}

[Solar Position module rendering]: https://biocro.github.io/BioCro-documentation/latest/doxygen/doxygen_docs_modules_public_members_only/classstandard_b_m_l_1_1solarpositionmichalsky.html#details "Documentation of the Solar Position module" {target="_blank"}

[dimensions]: https://en.wikipedia.org/wiki/International_System_of_Quantities#Dimensional_expression_of_derived_quantities "Dimensional expression of derived quantities (Wikipedia)" {target="blank"} [doxygen manual]: https://www.doxygen.nl/manual/docblocks.html "Doxygen manual" {target="_blank"} [physical quantity]: https://en.wikipedia.org/wiki/Physical_quantity "Wikipedia's entry on Physical Quantities" {target="_blank"} [coherent units]: https://en.wikipedia.org/wiki/Coherence%28units_of_measurement%29 "Wikipedia's entry on Coherent Units" {target="_blank"} [src/parameters.h]: r params$biocro_root/src/parameters.h "The BioCro parameters.h file" {target="_blank"} [unit tests for modules]: https://biocro.github.io/BioCro-documentation/latest/pkgdown/articles/an_introduction_to_biocro.pdf "Intro to BioCro vignette" {target="_blank"} [C++ Core guidelines]: https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines "C++ Core Guidelines" {target="_blank"} [aspects of coding and design]: https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#S-naming "C++ Core Guidelines' naming and layout suggestions" {target="_blank"} [Google C++ style guide]: https://google.github.io/styleguide/cppguide.html#Formatting "Google's guidelines for formatting C++ code" {target="_blank"} [Strategies to Speedup R Code]: https://datascienceplus.com/strategies-to-speedup-r-code/ "datascience+ article on speeding up R code" {target="_blank"} [Why loops are slow in R]: https://privefl.github.io/blog/why-loops-are-slow-in-r/ "Florian Privé's article on the pitfalls of R loops" {target="_blank"} [Lochocki et al. (2022)]: https://doi.org/10.1093/insilicoplants/diac003 "Lochocki et al. (2022)" {target="_blank"} [git-flow]: https://nvie.com/posts/a-successful-git-branching-model/ "git-flow" {target="_blank"}

[^public-API]: As of this writing, no C++ API for BioCro has been defined: there is no document that makes clear what publicly accessible portions of the framework and standard library are guaranteed to remain stable and available to be programmed against and which portions are subject to change.

[^reproducibility]: Irrespective of what dependencies BioCro now has or are added to it, a researcher who is concerned about reproducability should consider making a containerized version of BioCro. See, for example, the chapter Docker and Reproducibility in the document for the workshop Reproducible analysis and Research Transparency. The BioCro maintainers don't provide containerized versions of BioCro as we think this is a task better left to the individual researcher.

[^biocro_dependencies]: BioCro's strong dependencies are the R framework, the C++ compiler used in installing the BioCro package, the C++ Standard Library, the and the Boost C++ Library.

As for R package dependencies, the BioCro R package depends only

upon packages in the R standard library (stats and utils) for its basic installation and functioning. BioCro does use other, non-standard R packages for building the documentation and for testing, but these are not essential to a fully-functioning BioCro installation.

For further reading on the benefits and pitfalls of using

dependencies, see, for example, Russ Cox's article Our Software Dependency Problem and Bill Sourour's article Code dependencies are the devil.

[^compressing_vignettes]: If a package contains large vignette files, R CMD check may produce an error about overly large documentation. In this case, it can be helpful to specify --compact-vignettes=both when calling R CMD build. Previously this was an important issue for BioCro, but it has been mitigated by designating most vignettes as "web only."

Making Changes

Discuss first

By making changes without discussing it with the group, you risk spending time working on a solution that others may not accept. The members of the group also have diverse backgrounds and likely can give valuable design insights.

Follow BioCro's git branching structure {#branch-structure}

Etiquette for pull requests {#pr-etiquette}

We have several conventions when making and reviewing pull requests that are designed to make the process as efficient as possible, and to minimize any issues introduced by new code. These have been used in many PRs and have been found to be helpful.

Doing this will ensure that there are no basic issues when reviewers begin to look at the code. It may seem like a hassle, but it saves time in the long run. Even when the exact workflow above is not followed, the online tests can still be extremely helpful to a PR owner or reviewer:

Of course, the conventions above are not hard rules, and there may be situations where it is acceptable, or even necessary, to deviate from them. The following is a (non-exhaustive) list of situations where these conventions could be modified:

Making large modifications to BioCro

From time to time, someone will propose making a large change to the organizational structure of BioCro or to one of its central components. Here we also consider any modification that influences the way users or developers interact with BioCro to be "large." Large changes must be carefully considered and discussed before they are implemented. When considering such proposals, a number of key points should be kept in mind:

A friendly user experience makes BioCro accessible to a wide range of users who each have the potential to contribute to broader scientific understanding through modeling. Thus, it is important to minimize any barriers that may prevent some scientists from using it.

Distributing BioCro via CRAN is a key part of keeping it accessible to all users with maximum ease.

This has two implications:

There are a number of reasons for this:

BioCro has few dependencies, and all things being equal, we would like to keep it that way.[^biocro_dependencies]

If you propose a large modification to BioCro, please be prepared to discuss the following questions:

  1. How will time costs change for maintainers, developers, and users?

  2. Will there be more or fewer opportunities for BioCro to break due to changes in its dependencies?

  3. Which BioCro features will be added or lost?

Releasing a new version of BioCro {#new-release}

When releasing a new version of BioCro, it is essential to make sure that NEWS.md is up to date and that the new version is acceptable to CRAN. This can be achieved through the following steps:

  1. Choose the next version number; our conventions for semantic versioning are described in NEWS.md.

  2. Make a new release branch whose name is formatted as release-vX.Y.X, where X.Y.Z is the new version number, as described in the "Branching Structure" chapter.

  3. Update the DESCRIPTION file with the new release date (set to today's date), the new version number, and any necessary changes to the author list.

  4. Change the UNRELEASED header in NEWS.md to the new version number, and check the contents of this section to ensure it is clear and complete. It may be helpful to look through the list of completed pull requests on GitHub to check for any important changes that may have been missed.

  5. Run R CMD check to see any NOTEs that are reported; see the "Running R CMD check chapter" for instructions. Check the contents of cran-comments.md to make sure it accurately reflects the R CMD check notes.

  6. Make a pull request, requesting to merge the new branch into develop. In general, follow the guidelines in the "Pull Request Etiquette" chapter. However, there is one extra requirement for a release branch: the branch should not be merged until the new version has been accepted by CRAN. Sometimes CRAN may have issues with a new release, and it is better to address them before finalizing the release. (Otherwise, there may be several releases in quick succession with only minor or trivial changes between them; for example, BioCro versions 3.1.1 and 3.1.2.) See the "Submitting to CRAN" chapter for instructions.

  7. When the new version is on CRAN, merge the release branch into develop and then main.

Submitting a new version of BioCro to CRAN {#cran-submission}

The package maintainer is responsible for submitting to CRAN, and the process consists of the following steps:

  1. Build the package with R CMD build[^compressing_vignettes] using the current release version.

  2. Test the resulting .tar.gz file using R CMD check --as-cran using the current release version and the current development version on Linux and Windows. GitHub actions run this for R current Windows and Linux, and R devel Linux, so only R devel Windows needs to be checked locally.

  3. Attach the resulting .tar.gz file to the form here: https://cran.r-project.org/submit.html.

  4. Paste the contents of cran-comments.md in the form's comments box.

  5. Submit, cross fingers, and wait. If any issues are found by CRAN, address them and try again. If the checks fail only from permissible NOTES, such as using C++11, reply to the email indicating the justification, for example, we use a library that uses C++11. You can restate what is in cran-comments.md.

BioCro's online testing system should catch most issues before reaching this point, but sometimes CRAN starts enforcing rules that are not clearly explained anywhere or not checked by R CMD check. The most up-to-date description of CRAN's requirements can be obtained from the following official and semi-official sources, which each offer a different perspective on CRAN submission:

Code style

(Most of what is discussed here pertains specifically to code for the BioCro C++ library.)

Scientific considerations

Document sources and justifications in the code

Document units in the code

The following example shows how to indicate units in a number of different contexts. Note that, as in LaTeX, ^ is used to indicate a superscript, so that m^2 indicates square meters.

```c++
// In function signatures
double ball_berry(double assimilation,                   // mol / m^2 / s
                  double atmospheric_co2_concentration,  // mol / mol
                  double atmospheric_relative_humidity,  // Pa / Pa
                  double beta0,                          // mol / m^2 / s
                  double beta1)                          // dimensionless from [mol / m^2 / s] / [mol / m^2 / s]

// In assignments
double leaf_temperature = air_temperature - delta_t;  // K.

// In return statements
return assimilation_rate;  // micromoles / m^2 / s.

// In tables
const std::map<SoilType, soilText_str> soil_parameters =
{
    //                        d = dimensionless
    //                        d     d     d     J / kg      d     J s / m^3    d     d      d     Mg / m^3
    //                        silt  clay  sand  air_entry   b     Ks           satur fieldc wiltp bulk_density
    { SoilType::sand,       { 0.05, 0.03, 0.92,      -0.7,  1.7,  5.8e-3,      0.87, 0.09,  0.03, 1.60 } },
    { SoilType::loamy_sand, { 0.12, 0.07, 0.81,      -0.9,  2.1,  1.7e-3,      0.72, 0.13,  0.06, 1.55 } },
};
```

Document parameters

General coding considerations

Formatting code

(Again, except in a few instances, this pertains specifically to C++ code.)

The most important aspect of formatting is that the code is easy to understand. Below are unenforced preferences.

As for the code lines themselves, we point to the following advice from the Linux kernel project:1

The preferred limit on the length of a single line is 80 columns.

Statements longer than 80 columns should be broken into sensible chunks, unless exceeding 80 columns significantly increases readability and does not hide information.

For tools to help with formatting code, see the "Formatting Tools" section.

R-specific coding advice


1 The Linux kernel project recently changed the default length for code lines from 80 to 100 characters with the following commit comment:

Yes, staying withing 80 columns is certainly still preferred. But it's not the hard limit that the checkpatch warnings imply, and other concerns can most certainly dominate.

Increase the default limit to 100 characters. Not because 100 characters is some hard limit either, but that's certainly a "what are you doing" kind of value and less likely to be about the occasional slightly longer lines.



ebimodeling/biocro documentation built on June 12, 2025, 7:49 a.m.