The Forest Vegetation Simulator (FVS) source code is comprised of thousands of source files in dozens of directories. This document outlines the protocols for use of the open-fvs repository, which houses all of those files and directories. All users are expected to follow these protocols.

Please note that all FVS code is in the public domain, which means it is available to everyone. The open-fvs repository was set up so that anyone who visits can view and download code from anywhere within the repository.

If you are new to GitHub, GitHub Docs has several articles and tutorials for getting started. For working externally as a collaborator, please pay special attention to the sections on:

• Forking a Repository
• Syncing a fork
• Contributing to projects

The open-fvs repository is a Git repository. The best way to obtain the source code is through Git client software. References to several Git packages, along with instructions for obtaining the source code, can be found in the Downloading Source Code wiki document.

The open-fvs repository is administered by a group of Administrators. The Administrators are the only ones who can assign permissions to users.

Anyone can access and download source code from any part of the repository. However, only those who have been designated by an Administrator as at least having Write permissions are able to commit (or upload) code changes to the repository. Everyone designated with write permissions are expected to know and follow the protocols outlined in this document. If you need the ability to commit code changes, submit an issue through this site and explain why you need this capability. The Administrators will decide whether or not to grant your request. The Administrators reserve the right to deny permissions and to revoke permissions at any time for any reason.

The term Custodian is used throughout this document to refer to a developer who oversees a particular part of the repository. There may be more than one Custodian for a particular part of the repository. A Custodian is designated with at least write permissions. A Custodian for an area doesn’t have any more permissions in that area than any other developer.

Users without repository permissions can still contribute to the open-fvs project by creating a fork of this repository in their personal GitHub space. Users would then add this repository as an upstream remote to keep their local repository updated with the official code base. Edits made to users local forks can be included in the official repository by making 'Pull Requests' to the development branch. These pull requests will be reviewed by the open-fvs team, and a decision made on it inclusion in the official repository. More information regarding this process can be obtained by reviewing the GitHub Quickstart Guide, particularly the sections on forking a repository, and Contributing to projects.

FVS is comprised of a more than twenty geographic variants. A variant is a set of source code designed to represent a particular geographic area. All of the variants operate in a similar fashion, but each contains elements that are specific to its particular geographic range. For example, a particular variant recognizes only those tree species within its geographic range, and has geographically appropriate algorithms for things like tree growth and mortality.

The source code in the open-fvs repository can be compiled to build any of the FVS variant executables or shared libraries. Some of the source code files in the repository are used to build only one specific variant. Other source code files are used in the builds for multiple variants, or even all variants. Still others may be optionally included to add a particular extension to the base model.

Because some source code files are used in the builds of multiple variants, it is extremely important to note that any modifications you make to one source code file could potentially affect many, or even all, of the variants. You need to know the extent to which each source code file is used in the builds in order to minimize the risk of unintended consequences. The best way to find out which source code files are used in which builds is to look at the source list files included in the repository.

The build processes discussed in the Build Process wiki documents rely on source list files. These are simple text files that contain filenames and relative pathnames for all of the source code files used to build a particular FVS variant executable. Each potential executable has its own source list file. If you were to change the name or location of a source code file, you would also need to edit all of the source list files accordingly. Similarly, if you added a source code file, or deleted one, you would need to edit the source list files accordingly. So you can see that any sort of change to the repository files can have effects on many things.

The FVS source code is written in ANSI standard Fortran and C. This means FVS executables can be built for any operating system for which a suitable compiler exists. It is extremely important that this capability be maintained. If there is a chance that your code modifications will eventually be incorporated into the production FVS code base, you must stick to these languages, and you must adhere to the protocols used in the existing FVS code.

This does not, however, mean that there can be no interaction with other languages. Code has been written, and will likely continue to be written, to allow FVS to interface with products written in other languages. This code is typically not incorporated into the production FVS code base, but it may reside in the repository in an area designated for it by an Administrator. The custodian of this type of code remains responsible for keeping it compatible with the current FVS code.

The branching strategy utilized by the FVS team will closely follow the CIO Standard Branching Strategy with a few minor modifications.

For a review of Git Branching, please see the documentation at https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging .

All development shall occur in feature, or ‘working’ branches created specifically for the feature, issue, enhancement, or fix that is the propose of the code change. These temporary branches will be deleted, at least on a quarterly basis once the code changes have been reviewed and either merged with the primary development branch or discarded. No direct code committals shall occur to the primary developmental, staging, main, or release branches. Branch protection rules will be set up to enforce this practice.
A listing of remote and local branches can be viewed through a call to git branch -a. Users can checkout a remote branch to their local repository by calling git checkout <BranchName>. To create a new feature branch based on a previously checked out or local branch, issue the command git checkout -b <New-Branch> <SourceBranch>. This creates and moves the branch pointer to a new branch that is sourced from <SourceBranch>. All work will be done in the new feature branch.

It is extremely important to ensure updates made by other users, that have been merged into the primary repository development branch have been incorporated into your local feature branch and tested, issue the command git pull origin <ReferenceBranch>. This should be done regularly during the development process and is enforced by branch protection rules prior to submitting a pull request. Code commits and repository push updates should be done by git push –set-upstream <RemoteName> <New-Branch> the first time the new branch is added to the remote repository.

Code will only be committed directly to feature level working branches. Once the feature is ready to be merged into the primary development branch, a pull request must be created from the feature branch, requesting review from another member of the FVS staff, prior to merging the feature into the primary development branch for the repository.

Reviewers should add a note to the pull request that the code changes have been reviewed and are free of any ‘secrets’, passwords, API keys, usernames, or other potentially confidential or personal identifiable information. This is a somewhat of a departure from how committals have been done in the past, as staff were permitted to merge branches of their respective repositories without secondary review, and it will result in more work for staff, but this practice will ensure that in the absence of automated tools to preform code scanning, FVS maintains a documentable process of ensuring ‘cleaned code’ and clean commit history is eventually carried over to publicly available open-source code.

Once a feature branch has been merged into the primary development branch and no longer needed, it should be deleted from the local repository as well as from the remote repository. To delete a branch from the local repository, issue the command git branch -d <Feature_Branch_Name>. FVS repository admin will delete the merged branch from the remote repository. However, users may notice the removed branch will still show up in the list or available remote branches when calling git branch -a. To update the listing of branches on the remote repository, call git remote update origin --prune.

feature-branch - Developer created branches derived from, and kept in sync with, the development branch. These branches are intended for individual or quarterly feature updates and improvements. Once ready and tested, pull requests should be made against the development branch for the new feature(s) to be included within.

development - Ongoing quarterly updates sourced from and a compilation of user feature-branches. Should be consider the most up to date code, but not necessarily free from errors.

staging - Periodically, the development branch will be pushed into the staging branch. This branch represent up to date code that has been tested and verified, but may not contain all features and updates that are intended to be included in the next release.

main - The main branch contains the main set of source code that should included all features and is of release quality. It contains the most recent stable source code, makefiles, tests, and test outputs. There may be source code contained in main that is not yet available in the executables distributed through the FVS website (http://www.fs.usda.gov/fvs). Administrators are typically the only ones who commit code to main, and only after it has passed a series of tests. You should not commit code directly to main unless an Administrator has given you prior explicit approval to do so.

FMSCrelease - The FMSCrelease branch contains the source code from which the executables are created. It is updated from the main branch on a quarterly basis and should be the source for Release Tags.

tags - The tags directory contains several copies of FMSCrelease as well as other branches as they existed on a particular date or point in development. The tag name reflects the date or version number when the tag was created. For example, the tags directory named 2012-04-22 is a copy of main as it existed on April 22, 2012. The tags are created only by an Administrator, and once created they should not be edited in any way.

Other - There may be other branches in the repository. These were created for special auxiliary projects, and may not be derived from main. You should not modify any auxiliary directory unless you are its custodian or you have been granted explicit permission from the custodian to do so. If you need to modify the files in one of the auxiliary directories for which you are not the custodian, contact an Administrator to be put in contact with the directory custodian.

Administrators are the only ones who should ever merge branches into main.

Merging your branch into main is only required if your edited code needs to become part of the official FVS source code base and is first vetted in the open-dev and staging branches. If your code edits were made for something with a more limited scope than that, it is best to simply maintain your branch and not merge it into one of the development branches.

If you think your new or edited code might someday be merged into the official FVS source code base in main, it is in your best interest to contact an Administrator very early to discuss your ideas and try to ensure that your code edits will be appropriate for incorporation. As development proceeds, make sure to follow all of the coding protocols used by FVS developers.

There is no guarantee that your code will be incorporated into FVS. The FVS staff determines what will actually be incorporated. When an developer submits a pull request to a development branch, your logic and source code will be evaluated and rigorously tested. If the FVS staff determines that logic is deemed appropriate, your code passes evaluation, and the executables built with your code pass the tests, your code might be merged into main by an Administrator. If your branch is merged you will most likely need to include a new text file in the changeNotes directory to describe the changes or additions you made. This document should follow the format in the template.txt file in that directory, and the file name should follow the naming convention of the other files present. Edits to your code could occur with or without your knowledge, before or after merging into main. The Administrators reserve the right to reject code for any reason, and to remove previously included code for any reason. Be aware that merging code into main means it will be included in other people’s branches as they update their code. It also means that your code may be edited by others without any notification to you.

Once a branch has been merged into main, the standard practice is to delete the branch. If you still have a need for your branch after merging you should let the Administrator know, and your branch can be re-created after being deleted.

This section provides a brief list of the procedures typically followed during a project to edit the FVS source code. Many of the procedures are performed recursively, so this should not be viewed as a step-by-step set of instructions.

When you begin planning a code revision project, you need to decide whether you can use an existing branch for which you have appropriate permission. If you don’t have a branch, or if an existing branch won’t work well, you should create a new branch with a descriptive name for the major purpose of that branch.

Outside of the original creation of your branch and the potential merge of your branch back into main through first going through a development branch, Administrators will not perform any maintenance on your branch. To do so could have negative impacts on your project. Your branch of code is yours to manage.

Check out your repository branch to your local computer using the Git client software. If you don’t already have an Git client software package installed on your computer, install one. Refer to the Downloading Source Code wiki for references to several Git client tools.

Work in your local copy of your branch. Unless you have been given explicit permission from an Administrator, you should never commit code changes directly to main. You should only commit to your own branch or approved development branch.

When you are preparing to make code revisions, the first step should always be to make sure you are starting with the most recent code. If main has been updated since your branch was created, merge main into the local copy of your branch of the repository. Then commit your newly updated local copy of your branch to the repository so your branch in the repository contains the updated code as well. If you need assistance with any of these steps, contact an Administrator.

Create test files and other information as needed and commit changes frequently. It is important to understand that just because a new file has been added to your local working copy, that file is not automatically added to the repository. It will only exist locally. Use Git client options to ensure that files are added or deleted from the repository. If you need assistance, contact an Administrator or review the GItHub Quickstart Guide.

Routinely, as needed, merge main into your branch so that changes that have been made are included in the code in your branch. If you don’t routinely merge main into your branch it may be difficult to resolve conflicts that arise later when trying to merge. If you need assistance, contact an Administrator.

All code changes should be tested to ensure they have had the intended effect without having unintended effects. One way to do this is to identify values displayed in FVS output files that should change based on the edits, and others that should not change. Build a simulation that will generate outputs that can be used to test whether the appropriate changes have occurred, making sure to include the keywords needed to generate the necessary output files. Run the simulation using an executable built with code that did not include the edits, and then run the exact same simulation using an executable built with the edited code. Compare the outputs and make sure values have either changed appropriately (if they should have changed) or have remained the same (if that should not have changed).

The each branch should contain a tests directory, which contains the standard tests conducted by the FVS staff when edits have been made to the source code. Subdirectories have been set up primarily for different FVS variants. Each of these subfolders contains the files necessary to conduct the testing. Refer to the Testing wiki for more information.