Skip to contents

Development

2026-04-01

Source: vignettes/articles/DEVELOPMENT.Rmd
DEVELOPMENT.Rmd

This page is intended to provide overall guidelines for the MAPS development team. For others withing to contribute, please refer to our contributing guidelines.

By participating in this project, you agree to abide by our code of conduct.

Getting Started

  • Make sure you have a GitHub account and have been added to the MAPS development team. You will have to accept the invitation within seven days.
  • NOAA requires two-factor authentication for GitHub to increase security. You should recieve instructions when you accept the invitation. “Authy” is a good phone app for this purpose but there are many from which to choose.
  • If you’re not familiar with git or GitHub, http://happygitwithr.com/ is one of the best places to get started.

Style

  • R: Follow the Tidyverse Style Guide style guide
  • SQL: TBD

Basic Daily Workflow

  1. Pull (fetch and merge in one step) new changes from GitHub to your local
  2. Create branch if making substantial changes
  3. Make changes
  4. Add inidividual small changes to be staged to commit
  5. Commit changes
  6. Add (stage) additional small changes
  7. Commit changes
  8. Push changes to remote (GitHub) - do this frequently so others are starting with your changes when the pull. Always do when done working on a project for the day.

Production Workflow

Main (currently main) branch is the “release” production version and never gets modified directly.

develop is the primary branch to work in and from where branches should originate. This branch gets merged into the main branch for new releases (add release numbering info.). Release versions should be numbered using semantic versioning with major.minor.patch-dev (0.1.1-1 is the development version of the first version with one patch. When ready for release it’s changed to 0.1.1 and merged into the main. Then update to 0.1.2-1 on the development version). Major versions are not backwards compatible. Minor changes should be significant updates that are backwards compatible. The version is in the DESCRIPTION file and updates should be recorded in NEWS.md

features are branches from develop for supporting projects and modules and large test areas. Each feature branch should have a descriptive name. To add additional details, there should be a GitHub issue associated with each feature branch. Ideally the issue title would be the same as the feature name. This connects the reasoning behind the feature, changes, or module and documents any discussion and decision making. If the branch incorporates multiple issues, the issues should either be merged or the main issue associated with the feature or should include links to the other issues. After initial testing, this branch should be merged back into the develop branch.

There is also the potential to have hotfixes. These would be temporary branches from the main branch that are for very small but critical fixes. The process would be to branch from the main make the fix, test it, then merge into both the main and the develop branches. I’m not sure if this will be needed but it’s an option.

Issues

Make use of GitHub issues when adding or modifying any code. Use issues to plan changes, workflows, improvements, additions, and ask questions. The associated KanBan boards should be used to help keep issues with code development organized.

Making changes

  • Create an issue for each Git branch or change more in depth than a minor fix.
  • Edit the files, save often, and make commits of logical units, where each commit indicates one concept
  • Commits are the level you can most readily revert to if there’s a problem, therefore many small changes is much better than large changes.

Commit Messages

Follow standard git commit message advice. In brief:

The first line is the subject, and should summarise the changes in the commit in under 50 characters.

If additional details are required, add a blank line, and then provide explanation and context in paragraph format.

If the commit fixes a GitHub issue include Fixes #. This will ensure that the issue is automatically closed when the commit is merged into main.

Branching

An example workflow when wanting to create a new feature, module, or improvement would start by creating a new github issue or working with an existing issue in the to do panel of the kanban project board. Then create a new branch from the develop branch.

git pull origin develop
git checkout -b feature_8a24c1 develop

Now work on the feature and once you are happy with it and it’s been tested a bit you can bring it back into the develop branch.

git checkout develop
git merge --no-ff feature_8a24c1
git branch -d feature_8a24c1
git push origin develop

This is great because the new feature has been incorporated into the development branch but still has not affected the production (main) branch. Most of the time, we probably want to delete the old feature branch once it has been merged into the development branch and tested. To do this both locally and remotely (on GitHub) run the following code:

git checkout develop
git branch -d feature_8a24c1
git push origin --delete feature_8a24c1

When the develop branch has been sufficiently tested and the group is ready for a new production release, the development version can be merged into the main branch.

git pull origin develop
git pull origin main
git checkout main
git merge --no-ff develop
git tag -a v0.1.0
git push origin main
git push origin --tags
git checkout develop

Branches do not ever have to be merged back into the development branch or anywhere else. They can be left hanging indefinitely or deleted if you are sure you don’t want any of the code that was written.

A great, detailed guide on git branching for software production is at https://nvie.com/posts/a-successful-git-branching-model/. It is where these images came from.

Much, if not all, of this process can be done in RStudio now although it’s good to know the command line basics since more advanced troubleshooting will require using git via the command line. I am not sure if the merging in RStudio can be done with the --no-ff option.

Testing

Testing can be done in any features branch or hotfix. All changes should be tested fully on the develop branch prior to merging into the main branch.

When errors arise during testing that do not seem related to the new code being tested, these suggested steps can be taken to ensure files are synced.

  1. git pull origin main
  2. git checkout feature_8a24c1
  3. delete internal .fst files
  4. run internalData.R, ensuring the database is set to preprod at the top of the script
  5. devtools::document()
    1. devtools::test()
  6. devtools::install()
  7. check configRun.toml is set to preprod and that frontend is true
  8. start test run of MAPS

TODO: Eventually, separate paths/directories should be written during testing associated with any branch. Then maybe some automation can be set up to delete any associated directories when the branch is deleted.

Updating Configuration Tables

Occasionally a configuration table will need to be changed. The process for doing so is:

  • As needed, bring change to CAMS Change Management Board (i.e. any change that will propagate to end users)
  • Make update to .csv file in data-raw folder
  • Run internalData.R script in data-raw folder
  • Any changes to CFG table will result in update to the CAMS version. Confer with CAMS Change Management and/or programming team to determine what level version update your change will require. Update the cfg_version.csv file, which is found in inst/extdata.
  • Update news.md file with description of change and version number
  • Update the version in the description file
  • Run devtools::document()
  • If the change requires column updates (DDL updates), update relevant section of the setup_config function in the setup.R file.
  • Commit/Push to github, continue with standard branching/merging and installation protocol