Menu
▾
▴
RepositoryMgmtPolicy
Anonymous
FVS Home Repository Has Moved
Please note, the official FVS repository has recently migrated from Source Forge to GitHub. Please visit us at https://github.com/USDAForestService/ForestVegetationSimulator for the latest in code and wiki updates. This Source Forge repository will no longer be maintained, and is kept here as archival reference only.
REPOSITORY PROTOCOLS
INTRODUCTION
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.
REPOSITORY AND CODE OVERVIEW
Repository Type
The open-fvs repository is a subversion (SVN) repository. The best way to obtain the source code is through SVN client software. There are many different SVN client software packages, including some freeware packages. References to several SVN packages, along with instructions for obtaining the source code, can be found in the [DownloadingSourceCode] wiki document.
Repository Permissions
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 a Developer are able to commit (or upload) code changes to the repository. Everyone designated as a Developer is expected to know and follow the protocols outlined in this document. If you need the ability to commit code changes, submit a ticket 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 as a Developer, and has the associated permissions. A Custodian for an area doesn’t have any more permissions in that area than any other Developer.
Multiple-Use Source Code Files
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 wat to find out which source code files are used in which builds is to look at the source list files included in the repository.
Source List Files
The build processes discussed in the BuildProcess 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.
Programming Languages
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.
DIRECTORY STRUCTURE
The open-fvs repository is set up as the primary source code repository for FVS. It is meant to allow for collaborative application development. Repository terminology is (appropriately) based on a tree. The repository itself is the tree, and it has a trunk and branches.
You need to be careful to work only in your designated part of the repository. Each Developer or group of Developers is typically given a specific repository directory, known as a branch, to store the source code they modify or develop. A Developer or group of Developers for whom the branch was created becomes the Custodian of that branch. You should typically work only within branches created specifically for you.
The overall structure of the open-fvs repository is described below. Different levels within the repository structure are discussed in separate sections.
Tree-Level Directories
The tree level is the top level in the repository. There are several different directories at this level.
trunk - The trunk directory contains the main set of source code from which all subordinate sets of code originated. It contains the most recent stable source code, makefiles, tests, and test outputs. There may be source code contained in trunk 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 trunk, and only after it has passed a series of tests. You should not commit code directly to trunk unless an Administrator has given you prior explicit approval to do so.
branches - The branches directory contains several branches, which are subdirectories created by an Administrator for a particular Developer to store edited source code. The developer for whom a branch was created will be referred to as its custodian. Each branch was originally created as an SVN copy of trunk. You should commit code only to branches for which you are the custodian, or branches for which you have been given the explicit permission of their custodian to commit code. You should not commit code to other branches, other directories, or to trunk. Custodians are responsible for all maintenance of their branches, including keeping them updated with edits made to trunk.
tags - The tags directory contains subdirectories, each of which contains an SVN copy of trunk as it existed on a particular date. The subdirectory name reflects the date. For example, the tags directory named 2012-04-22 is a copy of trunk as it existed on April 22, 2012. The tags directories are created only by an Administrator, and once created they should not be edited in any way.
Other directories - There may be other directories at the tree level in the repository. These were created for special auxiliary projects, and are not derived from trunk. 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.
First-Level Subdirectories
Within the tree-level directories are a number of subdirectories, which, in turn, contain files and/or additional subdirectories. The subdirectories immediately within the tree-level directories will be referred to as first-level subdirectories. The subdirectories within the first-level subdirectories will be referred to as second-level, and so on.
As stated earlier, the trunk directory contains the main set of code, and the branches were originally created as copies of trunk, so the subdirectory structure in each branch was originally identical to that in trunk. The subdirectory structure described below is for trunk, but it should be fairly universal for branches and tags.
There are many first-level subdirectories. Most were set up to contain source code for a particular part of the FVS model. In this way, related code files are located in the same subdirectory. The subdirectory name is an abbreviated indicator of the part of the model to which its code pertains. For example, the subdirectory named dbs contains source code for the database model. It’s not always practical to keep related source code files in the same subdirectory, but you should make every attempt to maintain this type of logical order when modifying code in your branch.
Several of the first-level subdirectories are discussed below. Some have been grouped for discussion purposes.
common - The first-level subdirectory common contains declarations of variables and arrays used throughout the FVS code as globals. All files in common have filenames in all caps, and filename extensions of .F77. This is in contrast to the Fortran source code files in other subdirectories, which have filenames in all lowercase and extensions of .f. The files in the first-level common subdirectory are universal in that they can be included in the build for any geographic variant executable. There are other common subdirectories within some of the other first-level subdirectories. Those contain declarations of global variables and arrays used in particular variants or model components. Source code files in common subdirectories should be reserved only for global declarations.
base - The base subdirectory contains source code used to build the base model of FVS. The files in base are universal in that there is nothing in their source code that limits their use to a subset of geographic variants. The files could potentially be used to build any variant. If you modify source code in base you should make every attempt to keep it applicable to all variants. If you have to modify a source code file so that it is specific only to a subset of variants, you should move that source code file out of base and into the appropriate variant-specific directory. You should also move the original, unedited file to an appropriate variant-specific directory. Contact an Administrator if you are unsure of the appropriate locations for files. You will need to edit the affected source list files to reflect the new file locations.
Variant-specific subdirectories - Many of the subdirectories have names with the two-letter designation for a geographic variant of FVS. For example, the subdirectory named ie refers to the Inland Empire variant of FVS. Source code contained in the variant-specific subdirectories is used only to build that specific variant or a group of related variants. For information on the FVS variants and their two-letter designations, refer to the FVS website (https://www.fs.usda.gov/fvs/whatis).
Extension subdirectories - A number of the subdirectories contain source code for an FVS extension. Extensions are model segments that are typically optional to include in an executable. For example, many of the variants can be built with extensions that simulate the effects of insects or disease. The Essential FVS document, available from the FVS website (https://www.fs.usda.gov/fvs/documents/guides.shtml), describes the various extensions. For information about the various insect and disease extensions and the variants to which they apply, refer to the Forest Health Protection website (https://www.fs.usda.gov/foresthealth/applied-sciences/fvs-models).
There are a few special subdirectories that do not contain source code, and they are described below.
bin - The bin subdirectory does not contain source code. It contains files used to build executables. The procedure used to build executables is described in the BuildProcess wiki documents. Developers may need to modify the FVSxx_sourceList.txt files in their branch (where xx is the variant designation), but the files in trunk should not be updated. When builds are completed, your local bin directory may contain additional subdirectories and files related to the builds, including the executable files. These subdirectories and the files they contain should not be uploaded to the open-fvs repository.
changeNotes - The changeNotes subdirectory does not contain source code. It contains text files describing changes made to the source code. These files may be valuable to developers when trying to determine when particular features were changed in the code. You should not modify the changeNotes subdirectory in trunk unless an Administrator has given you explicit permission to do so.
tests - The tests subdirectory does not contain source code. It contains subdirectories and files needed to run tests on executables built with modified code. The required testing process is described in the [Testing] wiki document.
PROTOCOLS FOR DOWNLOADING AND UPLOADING FILES
Subversion (SVN) client software should always be used when downloading or uploading repository files. SVN software has a versioning system, so it knows when files have been modified. Using SVN software allows for reverting to previous versions of files if something goes wrong. Refer to the [DownloadingSourceCode] wiki document for some suggestions for SVN client software and instructions for downloading and uploading files. That wiki also contains information for configuring your SVN client software to access the open-fvs repository.
You will most likely download a local copy of just a part of the repository. For example, you may want a local copy of trunk or your branch. This is accomplished through the SVN client software using the Check Out feature (or equivalent). If you will be working in a branch, you can check out just that branch, creating a local copy of it on your computer. There is usually no need to check out the entire repository, which contains tens of thousands of files.
Once you have the local copy of part of the repository, you can automatically download only the files newer than the ones you already have. This is accomplished through the SVN client software using the Update feature (or equivalent). This will update your local files with any newer files contained in the repository. Protocols related to the update process are provided in the next section of this document.
Uploading files from your local copy to the repository is accomplished through the SVN client software using the Commit feature (or equivalent). This will update the repository with any newer files contained in your local copy. You should always include a “commit note” through the SVN client software whenever you commit source code files. Commit notes describe what has been edited, and they make it easier to track down the source of problems encountered later. Protocols related to the commit process are provided in the next section of this document.
PROTOCOLS FOR WORKING IN A BRANCH
Unless you have been given explicit permission from an Administrator, you should never commit code changes directly to trunk. You should only commit to your own branch or to a branch for which you have explicit permission from the custodian to commit code.
If you are a custodian for a branch or if you have explicit permission from a custodian, you are free to modify the files in that branch and commit your edited source code to it. If you don’t have this type of access to a branch, work with an Administrator to obtain access or to create a branch for your project.
All code committed to the repository should be free from known errors and should be capable of building the related executables on at least one operating system prior to being committed. In other words, we don’t want code in the repository that results in known errors or fails to compile or build correctly functioning executables. This protocol allows developers to assume that any failure in the compile or build process or any error in execution was introduced with new edits and did not already exist prior to those edits.
If you are working with other developers on a project, you should all use a common branch to reduce the risk of conflicts that can arise when attempting to merge source code developed separately.
The custodian of a branch should routinely merge trunk into a local copy of the branch to obtain any edits that have been committed to trunk, and then commit the newly updated local copy of the branch to the repository so the branch on the repository contains the updated code as well. This will help to ensure that all updates obtained from that branch are up to date with the latest trunk code.
Before you begin a project that will edit or use source code, it is best to update your local copy of the repository to obtain an exact copy of your branch as it exists in the repository. The easiest way to ensure that your code exactly matches the repository is to simply checkout a new copy of the branch. If you had been working on a prior project with the branch code, it may contain unversioned files that you wish to retain for your project records. In this case, you may prefer to change the name your working copy folder and save it with its associated project. There are also temporary/intermediary folders and files used during the executable build process that contain copies of source files and object files that are unnecessary to retain. These are the …_buildDir folders in the bin folder and can be deleted directly or by using the makefile in bin. To use the makefile to clean the repository, while at the command prompt in the bin folder enter command “make clean”. Temporary folder and object files will be removed and any other extraneous files will remain. For additional information regarding makefile use, please refer to one of the BuildProcess (https://sourceforge.net/p/open-fvs/wiki/browse_pages/) wiki documents. If you wish to just start fresh and continue to use your existing working copy folder, just delete all of the files in your local copy of the branch and then use SVN client software to perform an update, which will copy all repository files to your local copy.
If more than one person is working in a branch, all of you should frequently update your local copy of that branch. This will ensure that everyone is incorporating edits others have made. SVN client software should be used for this operation because it will ensure that you have the newest versions of all source code files, and will allow you to access previous versions if needed. When updating your local copy of the branch, if your local copy of a file is an edited version of that same file in the repository, the local copy will be retained. If someone committed an edited version of a file that you have not edited, the edited version will be downloaded. If you have edited a file and someone has committed an edited version of the same file, merging of code is attempted automatically, but you will encounter conflicts if multiple users changed common lines of code. You may need to examine both versions to determine how to resolve the conflict and commit the resolved version to the repository.
You are encouraged to commit code modifications frequently, particularly if others are working in the same branch, but you should always update your local copy of the branch before committing anything. This will ensure that you are incorporating any edits that others have committed recently. When you have completed edits to source code files and have verified that the code will compile and build correctly functioning executables, use your SVN client to update your code. If any files are downloaded you will need to re-compile, re-build, and re-assess to assure everything still functions correctly. If things don’t build or don’t function correctly, you will need to correct any issues. When you have ensured that correctly functioning executables are built, then do another update to make sure there have been no commits since you have been testing. If none of your local files are updated, then immediately commit your edits to the repository. Following this procedure will minimize the possibility of conflicts during the commit process. A brief description of the changes and/or purpose of modification should always be included as a part of the commit process.
If all users of a branch perform frequent updates and commits, any potential conflicts should be easier to resolve. Your edited code will also be updated in other people’s local copies more frequently, so as long as all branch users update their code regularly you will all be working with the most recent verified code.
Please note that all FVS code is in the public domain, which means it is available to everyone. Anyone who visits the open-fvs repository can view and download code from anywhere within the repository. This means that everyone has access to all of the code that you commit to your branch. It is very possible that someone will take your source code and modify it for their own purposes. There is no way to protect your files from others, and there are no plans to ever offer such a feature. If you don’t want your code downloaded or viewed by others, don’t put it in this repository.
Please note that there is no guarantee of any kind that files in the open-fvs repository are safe from deletion, corruption, unauthorized editing, malware, or any other sort of harmful content. You are strongly encouraged to keep local copies of all files you commit to the repository. Attempts are made to ensure that the files stored in the open-fvs repository are correct, complete, and up to date, but there is no guarantee of any level of correctness, completeness, or relevance of the files in the repository or of any product built or derived from these files. In other words, use files from the open-fvs repository at your own risk.
PROTOCOLS FOR MERGING YOUR BRANCH INTO TRUNK
Administrators are the only ones who should ever merge branches into trunk.
Merging your branch into trunk is only required if your edited code needs to become part of the official FVS source code base. 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 trunk.
If you think your new or edited code might someday be merged into the official FVS source code base in trunk, 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. When you have code that you would like merged into trunk, contact an Administrator.
There is no guarantee that your code will be incorporated into FVS. The FVS staff determines what will actually be incorporated. When an Administrator is notified of your desire to merge your branch into trunk, 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 trunk 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 trunk. 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 trunk 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 trunk, the standard practice is to delete the branch. If you still have a need for your branch after merging into trunk you should let the Administrator know, and your branch can be re-created after being deleted.
WORKFLOW PROTOCOLS
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.
If you don’t have a SourceForge profile, create one for yourself. If collaborators on your project will need to commit edited code, make sure they have a profile as well.
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, submit a request to an Administrator to create a branch for your project. Make sure the Administrator knows your SourceForge profile name so you can be designated as the branch custodian with Developer privileges to allow you to commit edited code to the repository. Make sure any others who will need to commit edited code have SourceForge profiles and request that they be designated as Developers as well. Administrators reserve the right to deny requests for privileges or revoke privileges at any time for any reason.
Outside of the original creation of your branch and the potential merge of your branch back into trunk, Administrators not will 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 SVN client software. If you don’t already have an SVN client software package installed on your computer, install one. Refer to the [DownloadingSourceCode] wiki for references to several free SVN 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 trunk. You should only commit to your own 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 trunk has been updated since your branch was created, merge trunk 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 SVN client options to ensure that files are added or deleted from the repository. If you need assistance, contact an Administrator.
Routinely, as needed, merge trunk into your branch so that changes that have been made to trunk are included in the code in your branch. If you don’t routinely merge trunk into your branch it may be difficult to resolve conflicts that arise later when trying to merge. If you need assistance, contact an Administrator.
If you would like to merge your code into trunk, consult with an Administrator as your development nears completion. If needed, the Administrator can assist you in merging your code into trunk locally. After the merge is complete and fully tested locally, the Administrator may approve the commit of your modified trunk to the repository. Never commit to the repository trunk without explicit permission from an Administrator.
CODE TESTING
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 directory trunk contains 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.
