RHESSys Git Repository
This page provides information about using Git to manage RHESSys source code.
The RHESSys Git repository contains at least two permanent branches named, "master", and "develop". There can also be temporary branches known as feature branches. In general, feature branches are used to represent one or more commits that implement a new feature or a bug fix. In most cases, a feature branch representing new features will be merged into the develop branch when they are deemed ready for testing by a wider group than those who have written the feature. Alternately, feature branches for bug fixes will usually be merged into the master branch to facilitate quick testing and release of the official bug fix release of RHESSys.
When a bug fix feature branch is merged into master, it must also be merged into develop to ensure that the experimental version of RHESSys (which will someday become the next official release) also receives the bug fix (unless the bug fix is not needed or has already been fixed in develop by some other means). The best way to do this is to first merge the branch into master. Then create another branch based on the bug fix branch that was just merged into master (make sure not to delete the initial bug fix feature branch yet). Into this new branch you will need to merge the develop branch, resolve any conflicts that arrise, and then push this branch to GitHub. Once pushed, you can create a new pull request to merge the new feature branch into develop.
Before creating a feature branch, that is before starting to do work on a new feature or bug fix, developers should create a new "issue" in GitHub (see here for more information). The purpose of the issue is to document the purpose of your feature or bug fix. Issues can be short, or can involve lengthly conversation over the proposed design and implementation approach of a feature or bug fix. Issues can also be labeled (e.g. "bug fix", "enhancement"), associated with milestones (i.e. a collection of issues with a due date attached), and assigned to people. Using labels, milestones, and assignees, GitHub issues provide a simple by powerful team management tool for smaller projects like RHESSys.
Issues will be assigned numbers when created. We'll use this number in several ways, including to name our feature branches (See below).
Feature branches must be merged by creating a "pull request" in GitHub (see here for more information on pull requests). The purpose of the pull request is to provide an opportunity for other RHESSys developers to review code before it is merged into either develop or master. Code review can help to improve software quality by providing a formal mechanism for peers to comment on the quality and style of code being submitted.
RHESSys uses continuous integration (CI) tools to ensure that RHESSys code always passes basic tests (e.g. compiles, maintains mass balance). The CI tests are run for each branch when a pull request is created. No branch should be merged if the CI tests are failing, or the CI tests may need to be updated if the RHESSys has changed significantly enough make the test datasets (e.g. worldfile) are no longer compatible with the current version of the model.
Feature branches under pull request cannot be merged unless they are up-to-date with the branch they would be merged with. A feature branch can become out-of-date with its base branch (i.e. develop if the feature branch was created based off of the development branch, see below) if the base branch has had changes merged into it since the time the feature branch was created (e.g. via an un-related pull request).
Once the version of RHESSys in develop has been tested sufficiently to warrant a new release, the develop branch can be merged into master, and then the current state of the master branch can be tagged with the version number, which will associate a specific commit with that release of RHESSys. See here for more information about tags and releases.
To create a clone of the RHESSys repository on your local computer, do the following:
git clone https://github.com/RHESSys/RHESSys.gitThis will create a new directory (within the current directory) that contains the repository.
To switch to the develop branch, use the "checkout" Git command:
git checkout developYou can always check what branch you are currently sitting in using the "branch" command as follows:
git branch --allThe active branch will be labeled with a "*"
The develop branch already exists in the GitHub RHESSys repository, so you can set this branch as active once you clone the repository to you computer. You should never commit your changes to the develop branch in your local repository. Instead, you must create a feature branch to organize the code for a particular feature or bug fix. To create feature branch based on the develop branch, do the following:
git checkout develop
git pull
git checkout -b $ISSUE_NUMBER-$DESCRIPTIONWhere $ISSUE_NUMBER is the number of the issue that describes this branch (see above), and $DESCRIPTION is a short description of the branch (use the dash character, '-', to separate words in the description.
This will create the new branch only in your local copy of the RHESSys Git repository. Do the following to push this new branch to the repository on GitHub:
git push --set-upstream origin $ISSUE_NUMBER-$DESCRIPTIONIf you are creating a bug fix branch, substitute master for develop in the above.
To add a file (or a directory of files and directories) to your local repository, use the "add" command:
git add <file>To change the name (i.e. move) of a file under version control, use the "git mv" command:
git mv <file>Note that Git doesn't track directories, but you can still change the name of a directory that has files under version control using "git mv"
To delete files under version control, use the "git rm" command:
git rm <file>Unlike in a centralized version control system, each Git user has their own local repository and can make numerous commits to this local repository before pushing your changes to the repository stored at GitHub, thereby sharing your changes with others.
Before you commit to your local repository, it is always a good idea to check the status of your repository:
git statusThe status command will list what files have been modified since the last commit, it will also list any files that are not under version control (i.e. any new files you you may have created).
Before staging a file(s) for commit, it is a good idea to perform a "diff" on the file to make sure you know what changes you will be committing:
git diff <file1> <file2> ... <fileN>You can also omit the file arguments to see a list of differences for all files.
To stage a file or files for committing, use the "add" command:
git add <file1> <file2> ... <fileN>Once you have staged new and existing files for commit, you can use the "commit" command:
git commitThis will commit changes to all files in your local repository currently staged for commit; the commit will be made to the active branch in your local repository (i.e. to a feature branch). You will be prompted to enter a commit message; you can also include a one-line commit message from the command line:
git commit -m "My commit message"No matter how you specify the commit message, this message should succinctly describe the changes you made to each file included in the commit. Note that you can reference issue numbers in the RHESSys GitHub issue tracker in your commit messages, to do so type one "#" followed by the issue number, for example "Addresses #2". We strongly recommend referencing issue numbers in commit messages as doing so will enable GitHub will to link these commits to your issues.
Once you have saved the commit message and exited your editor (if the message was not specified on the command line) the commit will complete. Note that this commit was done against the active branch in your local repository.
Use the "push" command to "push" the work you've done in your local RHESSys Git repository to the repository hosted on GitHub:
git push origin $ISSUE_NUMBER-$DESCRIPTIONThis pushes the changes made to your local develop branch into the branch named $ISSUE_NUMBER-$DESCRIPTION on the remote repository hosted at GitHub.
7. You've got a pull on me: Updating your repository to reflect changes to the remote GitHub repository
Stay current - update RHESSys code changes on your local machine to reflect changes made to the code on the RHESSys GitHub repository.
Make sure you are currently on the local branch you want to update on your machine (you can check which branch you are currently on with git branch. If needed, change what branch you are on with git checkout). Then use git pull to download recent changes made to that branch.
If you are collaborating with one or more other developers on a particular feature branch, from time to time it is necessary to update your local repository with changes from the remote repository hosted on GitHub; do this with the "pull" command:
git pullIt is also often necessary to perform a pull when you are pushing changes from your local repository to the remote GitHub repository. This happens when the remote repository has changed since you cloned it to your local machine, or since you have last performed a pull.
If you have made commits involving files in your local repository changes, and these files have also changed been modified by commits in the remote repository, Git will mark these files as conflicted. You will have to manually reconcile these conflicts before you can take further actions.