VersionManagement

Description

Development branches

Further development and maintenance of the Modelica Standard Library is performed with two branches on the public GitHub repository of the Modelica Association.

Main development branch

Name: "master"

This branch contains the actual development version, i.e., all bug fixes and new features. New features must have been tested before including them. However, the exhaustive tests for a new version are (usually) not performed. This version is usually only be used by the developers of the Modelica Standard Library and is not utilized by Modelica users.

Maintenance branch

Name: "maint/3.2.3"

This branch contains the released Modelica Standard Library version (e.g., v3.2.3) where all bug fixes since this release date are included (up to a new release, when becoming available; i.e., after a new release, the previous maintenance versions are no longer changed). These bug fixes might be not yet tested with all test cases or with other Modelica libraries. The goal is that a vendor may take this version at any time for a new release of its software, in order to incorporate the latest bug fixes, without changing the version number of the Modelica Standard Library.

Contribution workflow

The general contribution workflow is usually as follows:

1. Fork the repository to your account by using the Fork button of the GitHub repository site.
2. Clone the forked repository to your computer. Make sure to checkout the maintenance branch if the bug fix is going to get merged to the maintenance branch.
3. Create a new topic branch and give it a meaningful name, like, e.g., "issue2161-fix-formula".
4. Do your code changes and commit them, one change per commit. Single commits can be copied to other branches. Multiple commits can be squashed into one, but splitting is difficult.
5. Once you are done, push your topic branch to your forked repository.
6. Go to the upstream https://github.com/modelica/ModelicaStandardLibrary.git repository and submit a Pull Request (PR). If the PR is related to a certain issue, reference it by its number like this: #2161. Once a pull request is opened, you can discuss and review the potential changes with collaborators and add follow-up commits before the changes are merged into the repository.
7. Update your branch with the requested changes. If necessary, merge the latest "master" branch into your topic branch and solve all merge conflicts in your topic branch.

There are some special guidelines for changes to the maintenance branch.

• Every change to the maintenance branch has to get cherry-picked at the "master" branch (see above), too. One exception are pure changes to the "versionBuild" annotation as these have no meaning in the development trunk.
• Annotations "version" and "versionDate" must not be changed in a maintenance release.
• Since the version number can currently not be changed when releasing a new maintenance release (also known as bug fix release) the Modelica Standard Library utilizes the "versionBuild" annotation for this purpose. So should there be a new maintenance release in the maintenance branch then the "versionBuild" number needs to be incremented by one. At the same time the "dateModified" field needs to be updated.
  Example:

    annotation(version      = "3.2.3",
               versionDate  = "2019-01-23",
               versionBuild = 2,
               dateModified = "2019-01-23 07:40:19Z",
               revisionId   = "$F​ormat:%h %ci$")

  The "revisionId" field is a special annotation to mark a properly released (maintenance) version from unreleased commits.
  Example:

  Running the export command "git archive -o msl.zip v3.2.3" will expand the above "revisionId" place holder to something like:

  revisionId = "c04e23a0d 2019-01-23 12:00:00 +0200$"

As a recommendation, a valid bug fix to the maintenance branch may contain one or more of the following changes.

• Correcting an equation.
• Correcting attributes quantity/unit/defaultUnit in a declaration.
• Improving/fixing the documentation.
• Introducing a new name in the public section of a class (model, package, ...) or in any section of a partial class is not allowed. Since otherwise, a user might use this new name and when storing its model and loading it with an older build-version, an error would occur.
• Introducing a new name in the protected section of a non-partial class should only be done if absolutely necessary to fix a bug. The problem is that this might be non-backward compatible, because a user might already extend from this class and already using the same name.