- Table of contents
- Beta Branch
- Adding the beta branch
- Following changes
- Making your own branch
- Database upgrade
- Compiling things
- Trying individual source file updates
- Keep Client and Server synced
- Working with github
- Attached Files
Where normal release are done on the git master branch, there is a git beta branch for development.
Using the beta branch for changes/fixes which need a database change can be tricky. The beta branch does updates the database scheme at certain points, and when a new version comes out you cannot upgrade automatically, see Database upgrade.
Because of this, it's not recommended to run the beta branch as production version.
In other words; Once you installed and (auto) upgrade your database, other (minor or bigger) sql changes can follow without the version to be changed, so the auto upgrade script doesn't get triggered anymore.
You should keep an eye on the changed to the upgrade file (eq 10016to10017.sql) from the time you installed it, so you can apply those changes manually to your database.
Adding the beta branch¶
To add the beta branch to the initial DomotiGa_Installation, do:
$ git checkout -b beta --track origin/beta
If the branch is up-to-date and has no changes:
$ git pull Already up-to-date. $ git status # On branch beta nothing to commit, working directory clean
Following changes¶To see changes:
- use the git web interface
- use the standard git commands for this, for example git log.
- for a graphical interface try gitk:
Making your own branch¶
Branching is easy in git so for development it is a good idea to create a new (private) branch.
To create one based on the current state and switch to it:
$ git checkout -b my_branch Switched to a new branch 'my_branch'
Then do your development and when done and you can merge the changes to back to the beta branch.
For more information, see http://www.git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging.
DomotiGa performs an auto database upgrade when version number in Main.module is higher than version in Database. This is done using the upgrade/_XXXXX_to_YYYYY_.sql file with XXXXX being the current version number and YYYYY = _XXXXX_+1. During development the latest upgrade file is updated to support new protocols/interfaces, modules, device types etc.
The problem with working in the beta branch is that the database upgrade script is executed the first time you run with the new version using the current version of the update file. When now the upgrade file is updated, it will not be automatically executed again when you start Domotiga. So if the upgrade files changes you you have to do the changes manually by looking at the upgrade SQL file and run those which you don't have and run them manually against your database.
For more details, see Database Upgrade.
Recompile the latest ZWave wrapper if appropriate:
$ cd ~/domotiga/wrappers/domozwave $ make clean $ make $ sudo make install
Compile the Gambas binaries
$ cd ~/domotiga $ tools/compile.sh
Trying individual source file updates¶
If you want to try a specific patch in the beta branch that only effects one or a limited number of source files, you can check out only these source files and recompile DomotiGa.
If you, for example, want to try the newest version of CMQTT.class:
$ cd domotiga/DomotiGa3/.src $ wget https://raw.githubusercontent.com/DomotiGa/DomotiGa/beta/DomotiGa3/.src/CMQTT.class $ cp CMQTT.class ../../DomotiGaServer3/.src $ cd ../.. $ tools/compile.sh
Keep Client and Server synced¶
DomitiGa consists of two projects, the client (DomotiGa3) and the Server (DomotiGaServer3). The Client is largely a superset of the Server in the sense that it has code for the GUI where the server does not have this.
Changes to non-GUI code (and some other non-synced files[*]) should be kept synced, so if you change the client code, it should also be done for the server code and vice-verse.
To keep things synced you can remember what do did (git status/git log) and merge/copy the changes to the other component, use diff or use the toools/fixlinks3.sh and tools/rmlinks3.sh scripts.
[*] Non-synced files are: Main.module (different) and CItems.class, Client.module, JSONClient.module, ScreenFunc.module, XMLClient.module, XMLParser.module (client specific)
Working with github¶
The DomotiGa source code is hosted on github, https://github.com/DomotiGa/DomotiGa.
If you want to contribute code, you can fork the repo and get a own fork of it.
You will notice that your fork on gitbhub is not automatically updated when next things are checked in to the DomotiGa repo:
Syncing can not be done directly/from within github but must be done through a local repo.
Create a local clone/repo¶
- a remote/origin master and beta branch pointing to your fork on github
- a remote/upstream master and beta branch pointing to the DomotiGa repo on github
> git remote -v origin https://github.com/<handle>/DomotiGa.git (fetch) origin https://github.com/<handle>/DomotiGa.git (push) upstream https://github.com/DomotiGa/DomotiGa.git (fetch) upstream https://github.com/DomotiGa/DomotiGa.git (push)
Now you can create a local beta tracking branch:
$ git checkout -b beta --track origin/beta
Sync with the DomotiGa upstream¶See Syncing a fork to get the latest DomotiGa upstream beta branch changes in you local repo.
- Be sure to be on the local beta branch, git checkout beta, before syncing
- git fetch and git merge can be combined: git pull upstream beta
Push to your github fork¶
Push your local beta branch to your remote origin/github fork, see Pushing to a remote
If this fails with:
error: cannot run git-credential-cache--daemon: No such file or directory
try installing the git-daemon package.
After this, github should say "This branch is even with DomotiGa:beta"
As branching is easy/cheap in git it is good to create a separate topic branch for specific problem fixes or added functionality.
While you are doing your development you can/should commit your changes regularly to the topic branch so that you intermediate backups and so that the change does not become too big to review easily.
During your development the DomotiGa beta branch will likely progress and you likely want to get the latest stage once a while so you sync your local beta branch.
If you had a local topic branch, the start of of that branch is no longer at the head of the beta branch but at the previous head. That is no problem but when you like to have the beta branch changes also "in" you topic branch you need to rebase your topic branch on the beta branch.
The process of moving the base of a branch to the head of another branch (or commit) is called rebaseing.
- Make sure you have no local modified or staged stages, but that they are all committed to your topic branche(s)
- Sync your local beta branch with the DomotiGa upstream
- Rebase your "topic-branch"
$ git status # On beta master nothing to commit, working directory clean $ git pull upstream beta $ git checkout topic-branch $ git rebase beta
Initiate a pull request¶
When you tested things and verified it and you like to add the code to the main DomotiGa repository, you can initiate a pull request to the core development team asking them to merge it.Steps:
- Rebase your topic branch to the head of the upstream/DomotiGa beta branch
- Push your topic branch to github
- Initiate a pull request:
- Log in on github
- Switch (in github) to your topic branch
- Click the Compare & review button
- Review the pull request
- Change the "compare" from DomotiGa:master to DomotiGa:beta
- When ready to submit your pull request, click the Create pull request button.
Sync remote branches¶
If you delete a branch on github (after it is merged), you can also remove it from your local repository using:
git remote prune github
provided that your github remote is called 'github'.