Git Information

GIT information

github introduction: https://try.github.io

github cheat sheet: https://github.com/tiimgreen/github-cheat-sheet/blob/master/README.md

For Spawn of EnergyPlus, which is in development at https://github.com/lbl-srg/modelica-buildings/issues/1129 the program https://git-lfs.github.com/ needs to be installed.

Structure of branches used in the Buildings library

Below are information for a typical workflow. We use the following branching model:

Branch	Description
master	Developments are merged into the master branch when they are complete.
issues	To fix issue or add a new feature, open an issue and then create a new branch with the name issueXXX_doc` where ``XXX is the number of the issue, and doc is a descriptive name, such as solarCollector if this is a bug fix for a solar collector.
release	Official releases are prepared on this branch. In this branch, the Buildings directory does not contain the version number, as this would make it impossible to automatically merge pull requests through the github web interface. The Buildings directory contains the help directory with the html help files.
1.5+build.1	These branches include official releases. They are built automatically from the release branch and tagged as 1.5+build.1. The Buildings directory is renamed to include the version number, such as Buildings 1.5.
maint_7.0.x	These branches are maintenance branches that only include backward compatible changes. They must be compatible with, for example, 7.0.0 without a conversion script. They generally don't contain new classes.

Official versions are tagged and developed from the release branch.

Hence, all development forks of and, once it is tested and stable, merges into the master branch. The release branch only gets updated with code that is close to a release.

Make changes on the master of your own fork

To fork the main branch to your own repository, make changes there, and issue a pull request, proceed as follows:

First, on the web interface, press Fork to fork the repository to your account. Next, run

git clone https://github.com/YOUR_LOGIN/modelica-buildings.git
# Make some changes
cd modelica-buildings/
# Add a remote upstream so that you can get changes from the master branch
git remote add upstream https://github.com/lbl-srg/modelica-buildings.git
# Fetch upstream changes, without changing local files
git fetch upstream
emacs README.md
git commit -m "Made changes to README.md" README.md
# Merge the changes from the upstream master (the main repo) with your local files
git merge upstream/master
# Push the changes to your repository
git push

Finally, on the web interface of your account, issue a Pull Request so that the changes are merged to the master branch.

Make changes using a branch of the master branch

To add a new feature, we open a new ticket, then branch of from the master branch, add the feature, and when it is stable, issue a pull request from the branch to the master. As an example, we show below how to modify the README.md file. Suppose this is for issue number 10. Then, we create a new branch which we call issue10_updateReadme.

git clone https://github.com/lbl-srg/modelica-buildings.git
  Cloning into 'modelica-buildings'...
  remote: Counting objects: 68, done.
  remote: Compressing objects: 100% (35/35), done.
  remote: Total 68 (delta 13), reused 66 (delta 11)
  Unpacking objects: 100% (68/68), done.
cd modelica-buildings/
git branch
  * master
git checkout master
  Already on 'master'
git checkout -b issue10_updateReadme
  Switched to a new branch 'issue10_updateReadme'
git branch
    master
  * issue10_updateReadme
echo "Added a line in issue10_updateReadme" >> README.md
git commit -m "Updated README.md" README.md
  [issue10_updateReadme 25b562c] Updated README.md
   1 file changed, 1 insertion(+)
git push origin issue10_updateReadme
  Counting objects: 5, done.
  Delta compression using up to 4 threads.
  Compressing objects: 100% (3/3), done.
  Writing objects: 100% (3/3), 397 bytes, done.
  Total 3 (delta 0), reused 0 (delta 0)
  To https://github.com/lbl-srg/modelica-buildings.git
   * [new branch]      issue10_updateReadme -> issue10_updateReadme
echo "Added a second line in issue10_updateReadme" >> README.md
git commit -m "Updated README.md a second time" README.md
  [issue10_updateReadme f8f29c5] Updated README.md a second time
   1 file changed, 1 insertion(+)
git push
  Counting objects: 5, done.
  Delta compression using up to 4 threads.
  Compressing objects: 100% (3/3), done.
  Writing objects: 100% (3/3), 384 bytes, done.
  Total 3 (delta 1), reused 0 (delta 0)
  To https://github.com/lbl-srg/modelica-buildings.git
     25b562c..f8f29c5  issue10_updateReadme -> issue10_updateReadme

Now, through the web interface, we can make a Pull Request to have the changes merged into the master.

Note that in the first push command, we used git push origin issue10_updateReadme to have the branch pushed to the github servers.

Once the Pull Request is merged into the master (typically by Michael), the branch issue10_updateReadme can be deleted on the server and the local repository by typing

git push origin --delete issue10_updateReadme
  To https://github.com/lbl-srg/modelica-buildings.git
   - [deleted]         issue10_updateReadme
git branch -D issue10_updateReadme
  Deleted branch issue10_updateReadme (was f8f29c5).