SMS++ Project Developer's Guide

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:

• Gitflow Workflow, a tutorial by Atlassian
• git-flow cheatsheet by Daniel Kummer

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.

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.