Skip to content

SMS++ Project Developer's Guide

Jump to bottom
Niccolò Iardella edited this page May 2, 2021 · 10 revisions

In this page you will find the concepts you must be familiar with to develop either the SMS++ core library or one of its modules.

Contributing

Each module has a CONTRIBUTING.md file containing the guidelines you must follow in order to contribute to the module repository. Please take a moment to read it before developing the module.

Workflow

The development of the SMS++ library and of all its modules follows the gitflow branching model. Its key concepts are:

  • The develop branch contains the latest development changes, while the master branch contains the latest stable release.

  • New features are developed via feature branches, that are created from the develop branch and are merged back into it when the feature is ready to be added to the module.

  • When maintainers decide to issue a new release, a new release branch is created from develop. When the release is ready, the release branch is merged into master and back into develop.

We strongly recommend using the gitflow-avh Git command line extensions, or a proper Gitflow extension for your IDE.

See the following resources for further details:

Note: Always leave the develop branch at least in a compiling state! Failing to do so may disrupt the work of other developers.

Versioning

The SMS++ core library and of all its modules adhere to Semantic Versioning. This means that, given a version number MAJOR.MINOR.PATCH, you should increment the:

  • MAJOR version when you make incompatible API changes,
  • MINOR version when you add functionality in a backwards compatible manner, and
  • PATCH version when you make backwards compatible bug fixes.

Changelog

Each module contains a CHANGELOG.md files documenting changes made, bugs fixed and features added. The changelog follows these guidelines.

Developers should update it regularly during the development, since the content of the changelog goes straight into the release notes every time a new release is issued.

About testing and tools

The SMS++ project contains two types of tests: unit tests and system tests.

  • Unit tests should be used to test single SMS++ modules. For example, the unit tests of SMS++ core library should test if Variables, Functions, Objectives and the other core components work as they should.

  • System tests should be used to test the interaction between multiple modules. For example, one could test if a MILPSolver can solve a UCBlock.

Unit tests should be included into their respective repositories. System tests should be included into the SMS++ system tests repository.

The reason behind this is that system tests add horizontal dependencies between modules that would be otherwise indipendent. For example, if one adds in MILPSolver repository a test that requires UCBlock, the MILPSolver will unnecessarily have UCBlock in its requirements.

If you are unsure were to put your tests, consider this rule of thumb:

  • If your test is using just your module (or a requirement your module already depends on), you can put it as a unit test in your module's repository (test directory, for custom).
  • If your test is using your module and another indipendent module, put it in the system tests.

The same applies with tools:

  • If your tool is using just your module (or a requirement your module already depends on), you can put it in your module's repository (tools directory, for custom).
  • If your tools is using your module and another indipendent module, put it in the SMS++ tools repository.

How to do a release (mantainers only)

When the decision to do a new release has been taken, follow these steps to issue a new release. The following instructions assume that you are using the gitflow-avh Git command line extensions.

  1. Create a new release branch from develop.

    git flow release start 'x.y.z'

    where x.y.z is the new version.

  2. Commit the last minute bugfixes in the release branch.

    Note: Do NOT commit other stuff here, only bugfixes.

  3. Bump up the version number in the all the files that have it. These may include:

    • CMakeLists.txt
    • conanfile.py
    • Doxyfile

  4. Update the changelog:

    • Add the new features and fixes in a new section:
    ## [<new_version>] - yyyy-mm-dd

    • Move everything from the [Unreleased] section to the new one. If you kept the former updated during the development, it should contain all the new stuff already.

    • Update the links at the bottom of the changelog file.

  5. When you are ready to make the release final, finish the release branch. This procedure merges the branch back into master and develop, and pushes the branches and the new tag to the remote repository:

    git flow release finish 'x.y.z' -m "Release version x.y.z" -p

    If you get prompted for the merge commit messages, you can leave the default ones. The sequence to close the vi editor and continue is :wq.

  6. Now the Gitflow release is in the repository. To take advantage of the GitLab Releases feature and show the release on the project page, do the following:

    • Go in the Tags page of the project, usually:

      https://gitlab.com/smspp/<project-name>/-/tags

    • Edit the release notes of the new tag (the one corresponding to the release you are issuing). Here you can copypaste the new stuff from the changelog.

    • The new GitLab release should now be available at:

      https://gitlab.com/smspp/<project-name>/-/releases

  7. Update the submodule reference in the umbrella project, or ask a maintainer from that project to do that for you.

Clone this wiki locally