-
Notifications
You must be signed in to change notification settings - Fork 26
Downloading Source Code
The Forest Vegetation Simulator (FVS) code is comprised of thousands of source files housed in dozens of directories. Trying to understand the code can be intimidating and confusing, but obtaining the code and building the executables is relatively simple if you follow the instructions in the appropriate wiki pages. This wiki focuses on obtaining the code.
The open-fvs file repository is an open-source Git repository. Anyone can download the source files, but you will need Git client software in order to do it.
If you are new to GitHub, GitHub Docs has several articles and tutorials for getting started. For working internally and externally as a collaborator, please pay special attention to the sections on:
There are several variations of Git client software available to meet your particular working style. Git can be integrated into and ran via a terminal, through a stand-alone graphic user interface (GUI) such as GitHub Desktop or Tortoise Git, and is often integrated into many of the commonly used text editors and integrated development environments (IDEs).
The basic Git software as well as a number of Git GUI Clients can be downloaded from the Git website at https://git-scm.com/downloads.
This repository makes use of submodules. If cloning for the first time, the submodule(s) can automatically be downloaded by including the --recurse-submodules flag to the git clone command line call:
git clone --recurse-submodules https://github.com/USDAForestService/ForestVegetationSimulator.git
If this flag is forgotten during the initial clone, or otherwise is missing from an update, the submodules can be initialized and updated through a call to git submodule init followed by a call to git submodule update
If you are new to Git and GitHub, the GitHub documents site offers a quickstart guide that may be helpful.
Only designated collaborators and teams will be able to commit code changes directly to the official repository. This means general users will need to create a fork of the official repository into their own space on GitHub. A personal fork will allow a user to experiment with the code without affecting the upstream repository. For more information about forks, please review this GitHub Doc.
Once you have created a fork of the official repository, you will need to clone the repository to actually copy the source code to your local computer.
If you intend to be a contributor to the official repository, you will want to make sure to keep your local repository and fork synced with the official repository. You will also want to read the section below on how to contribute your modified code to the official repository.
Repositories can be cloned from the command line or terminal using a few different protocols such as HTTPS or SSH. More information regarding these protocols can be found in this GitHub doc.
When cloning via the command line or terminal, you will first want to navigate to the directory location in which you wish to copy the repository. Please note that when the repository is cloned, it will create a new folder, of the same name of the repository being cloned, in your working path. Therefore, it would be counter productive to clone the repository into a location of the same name as it would create a duplicate folder name.
A repository clone preformed when the following is the active location in the command line or terminal:
C:/code-repositories
Would generate the following path for the cloned repository:
C:/code-repositories/ForestVegetationSimulator
However a clone preformed in a path named:
C:/ForestVegetationSimulator
Would generate the following path for the cloned repository:
C:/ForestVegetationSimulator/ForestVegetationSimulator
If cloning your fork of the ForestVegetationSimulator via HTTPS, the command line or terminal command would be:
git clone https://github.com/YOUR-USERNAME/ForestVegetationSimulator.git
Where YOUR-USERNAME is replaced with your actual GitHub user name.
Git GUI clients, including those built into the popular IDEs and code editing software, vary considerably. Generally speaking, GUI clients would have a dialog box where the user can enter the url of the desired repository to clone. Please review the documentation for your GUI of choice for specifics.
You will likely want to keep your local repository and fork synced with the official repository. You will need to do this by adding the original source repository as an upstream remote to your local repository. Again, the GitHub Quickstart Document provides detailed information on how this can be accomplished.
Once you have added the official repository as an upstream remote to your local repository, you will need to sync the upstream repository to your local by fetching the latest upstream information and merging it into your local repository. Once again, GitHub has excellent documentation regarding this process to meet your particular working style, whether it be through the web UI, or command line.
Only designated collaborators and teams will be able to commit code changes directly to the official repository. The general user will need to crate 'Pull Requests' from their personal fork in order for their code to be considered for inclusion into the official repository. These 'Pull Requests' should only be made to the 'development' branch of the repository. Rules and procedures for commits are covered in the Repository Protocols wiki page. All contributors are expected to read that document and follow the rules it contains.