Workflow for code changes

This page describes the workflow for changing source code and documentation. Eventually, as the design becomes more stable, we will define a stricter process. At this stage of the development, code changes should be done as follows:

Backward compatible changes

1. Open a new issue, and assign it to the one who can address it (which may be you).
2. Make a new branch starting from the master branch. Call this branch something like issue17_enthalpySensor, that is, use the issue number and a brief description of the revised feature.
3. Document your changes on the issue tracker and implement them on the branch.
4. If you correct a bug, it is good practice to implement a unit tests that reproduces the bug, and then show that your revisions correct the bug. This unit test then becomes part of the unit tests of the library to ensure that the bug does not appear again if others make changes to the code. In general, implement several unit tests that simulate the model for all different configurations, including forward, reverse and zero flow to make sure that all equations are tested and their results stored and compared when running unit tests.
5. When done with the implementation,
   1. merge the latest version from the master to your branch,
   2. run the unit tests,
   3. make a pull request from your branch to the master,
   4. assign the issue to Michael for review and for merging it the master branch. (Conversely, Michael will assign his changes for review to someone else.)
6. When reviewing other's code, add your comments on the issue tracker.
7. If the revisions are reviewed and correct, merge the pull requests to the master, delete the branch and close the ticket. If the revisions need further work, assign the issue to the original author.

Note that only the person who reviewed the code will merge it to the master. Don't merge your own revisions without having them reviewed.

Non-backward compatible changes

We consider changes to be non-backward compatible if they can break existing models. Examples include

1. Removing or renaming public variables, public parameters or public constants.
2. Removing or renaming classes (models, packages etc.)
3. Adding or changing assert statements.

The following changes are backward compatible.

1. Changes in documentation.
2. Changes in equation or algorithm section.
3. Adding new classes, or new variables and new parameters, as long as the parameters have a default value.

For non-backward compatible changes, the following steps are required:

1. Tag the issue and the pull request with the non-backward compatible tag.
2. Get the OK on the pull request from the library developers of AixLib, Buildings, BuildingSystems and IDEAS within 2 weeks of finalizing the pull request. If there is no response, then we proceed with the pull request.