Open-Source Contribution
- Jonas Van Duijvenbode
Forest Foresight is an open-source project and is trying to attract a thriving open-source community. To make the contribution process as smooth and enjoyable as possible we have defined several workflows and guidelines for the development of Forest Foresight. The topics are as follows:
Coding standards:
Style guidelines
Testing
Code quality
Dependency management
Issue management
Contribution process
Please read through these guidelines and contact us if anything remains unclear.
Also feel free to join our Discord channel where we discuss the open source package here
Coding standards
To keep the codebase manageable and uniform we have defined a couple of coding standards that we strive for. These are also the elements that contributions will be reviewed on.
Style guidelines
Styling guidelines are important to keep the code easy to read and uniform. We decided to go with the most widely used style guideline for R which is the tidyverse. For any details, please refer to their documentation. To make maintaining this guideline as easy as possible we use the following packages:
Lintr: This R package automatically checks the source code on tidyverse compliance.
Styler: This R package automatically fixes a lot of formatting issues. Please note that styler will never change any functionality and is unable to change naming issues for instance.
Please run both tools before submission to identify any issues before review. Note that the output of lintr is a guideline, if you have good reason to violate an issue, please mention it. Common sense has the final say here.
Code quality
To keep this package as easy to use, maintain, and extend as possible we strive to adhere to some software engineering guidelines. The main aspects that contributions will be reviewed on are the following:
Functional decomposition: preferably, each function should have one well-defined responsibility. Please ensure that any functions you write are decomposed.
Simplicity: before submission, please ensure that the code you’ve written is as easy to understand as possible.
Naming quality: please choose descriptive, unambiguous names that are easy to understand. We prefer verbose descriptive names over short ambiguous abbreviations.
Documentation: Before submission, please double-check whether the introduced changes have appropriate documentation, and any changed functions also have their documentation updated if applicable.
Testing and Checking
Testing is important to ensure correct execution and ease of change for the codebase. However, it is also an investment to test exhaustively. Because of this we have chosen to require two types of tests for new contributions:
Unit tests: if a new feature is added to the codebase, we require that each function has unit tests that cover its expected behavior. To implement this test, we use the testthat package.
Regression tests: if the contribution fixes a bug, then please add a regression test that tests for that bug’s behavior. This will help us catch bugs in the future and prevent them from happening again in the future.
R Check: In addition to unit and regression tests, we utilize R Check to ensure the overall quality and compliance of our R packages. R Check can be run using rcmdcheck::rcmdcheck() or devtools::check().
Please refer to the documentation for any specifics, or the repository for any examples. If real data is needed to test properly, the test_data folder in the repository provides a minimal data set for testing.
Please run all tests and check locally before submission to repo to ensure that the contribution did not unintentionally break other functionality.
Please note that more testing is always welcome. However, this is the minimum requirement for new contributions and will be tested for in the code review.
Dependency management
To simplify dependency management and package version related issue we have decided to use the renv package. Renv helps you to make sure that when you are working on the project everyone uses the same (versions of) dependencies during development and testing. There are two main workflows you need to be aware of:
Loading all dependencies at the start of a session: simply call renv::restore() to load all dependencies into the current session.
Adding a new dependency to the project: call renv::install(“package”) to install the dependency you want to add, then call renv::snapshot() to store the packages data into the lockfile. On your next commit, make sure to also commit the renv.lock file to the repository to update your peers automatically.
Please refer to the documentation linked above for additional details and uses.
Issue management
The Issues page on our GitHub repository is the main place where you can find how to contribute to the project. Issues come in two types:
Feature request: concerns updates or additions to the project.
Bug fix: concerns discovered bugs and unexpected behavior.
These issues can be submitted by anyone but are reviewed by the repository maintainers. Please note that only issues that are marked “confirmed” are guaranteed to be merged into the codebase.
Contribution process
This workflow guides contributors on how to address existing issues to the repository in alignment with our branching, testing, and styling strategies. A condensed version of this can also be found on the repository.
Assign the Issue: Find an open issue that you would like to work on. If there is no assignee, check the comments to ensure no one else is already working on it. Then, write a comment indicating your interest in working on the issue. Maintainers may review your request and assign the issue to you.
Fork the Repository: If you have not already, fork the repository to create a copy under your GitHub account. This will allow you to make changes without direct access to the main repository. You can start working on the `develop` branch or create a specific branch for the issue in your forked repository.
Develop and Test your changes: After making the necessary changes in your branch, follow the Testing Strategy to ensure your changes are covered by unit tests sufficiently. Also ensure code quality by running the styler and lintr checks, you can follow the instructions in the Tools section to use styler and lintr. Make sure that all code meets the project’s standards before submitting.
Create a Pull Request (PR): Once your changes are completed and tested, open a PR from your forked repository’s branch the main repository’s develop branch. Ensure your PR clearly references the issue it addresses, follows our testing and styling guidelines and is ready for review by maintainers.
Review and Respond: Wait for maintainers to review your PR. They will approve the PR if it meets all criteria, or they will request changes if any adjustments or improvements are needed.
If changes are requested, you should respond to comments and make the requested changes. Afterwards, push the updates to your branch in the forked repository which will be reflected on the PR.
Approval and Merge: Once your PR is approved, a maintainer will merge it into the develop branch in the main repository. After the merging, the issue will be closed, and your contribution will be part of the project.
Configuration management (config.yml)
Since version 4.0.0 (2024-12-07), ForestForesight has utilized a configuration file to manage environment variables and constants. This configuration file, named config.yml, must be placed in your R working directory. You can check your working directory or set a new one with these commands:
> getwd() #check if there’s config.yml in your working directory
> setwd(‘path/to/some/directory’) # set new working directory and make sure you have config.yml there
Below is an example of config.yml.
URL_MARKDOWN: "https://raw.githubusercontent.com/jduijvenbode-WWF/ForestForesight/main/README.md"
AWS_BUCKET_NAME: "forestforesight-public"
AWS_BUCKET_REGION: "eu-west-1"
EARLIEST_DATA_DATE: "2021-01-01"
DEFAULT_GROUNDTRUTH: "groundtruth6m"
DATA_FOLDER: "C:/Kodingan3/FFdata" # Make sure you use '/' not '\'
TEST:
DATA_FOLDER: "../test_data"
FF_PREP_QC_DATE: "2021-01-01"
COUNTRY: "BRN" While most of the values in config.yml are not likely to be changed, you can define your own constants, such as “DATA_FOLDER” or even add new variable. Please note that all variables in the example above must be defined in your config.yml file to ensure proper package execution.
All variables in config.yml are loaded into the system environment by calling the config_load function. This function is automatically called when you load ForestForesight package (see code below).
library(ForestForesight) # Automatically runs config_load
config_load() # Call this to reload values after config.yml modifications Note: If you add or change the variable or value in config.yml, remember to call config_load()to apply the new or updated value or alternatively reload the ForestForesight library. For more information about the config file please refer to the configuration page.
Here are some examples of config variables in action.