Version Control System (VCS) Guide

Version Control Systems (VCS) are extremely important tools for managing codebases, tracking changes, and collaborating with other developers. This guide provides an overview of VCS concepts, common workflows, and best practices that we follow at OSN.
This is not a tutorial on how to use Git or SVN, but rather a guide on what standards we follow at OSN.

What VCS do we use?

At OSN, we prefer using Git as our primary VCS. Git is a modern, distributed VCS that is widely used in the industry. For more information, refer here.

We also use Subversion (SVN) for some of our projects. SVN is a centralized VCS that used to be popular before Git. It usually does not have as many features as Git, but it is still widely used in some organizations. For more information, refer here.

We use GitHub as our Git hosting platform. As for SVN, we have our own SVN server: svn.onesoftnet.eu.org.

Introduction to Semantic Versioning

Semantic Versioning (Semver) is a versioning scheme that is widely used in the software industry. It is a simple set of rules and requirements that dictate how version numbers are assigned and incremented. The format is as follows:

MAJOR.MINOR.PATCH

MAJOR: Incremented when you make incompatible API changes.
MINOR: Incremented when you add functionality in a backwards-compatible manner.
PATCH: Incremented when you make backwards-compatible bug fixes.

For more information, refer here.

OSN Projects follow a superset of Semver.
In addition to the rules described in Semver, we also have the following rules:

Pre-release versions: We use the -alpha, -beta, and -rc suffixes for pre-release versions. For example, 1.0.0-alpha.1, 1.0.0-beta.1, 1.0.0-rc.1. Each of these suffixes have specific meanings:
- -alpha: This is the first stage of the release cycle. It is used for initial testing and feedback, when features are still being added.
- -beta: This is the second stage of the release cycle. It is used for feature complete testing and feedback.
- -rc: This is the third stage of the release cycle. It is used for final testing and feedback before the final release.
Build metadata: We use the + suffix for build metadata. For example, 1.0.0+exp.sha.5114f85. This can be used to identify the build number, commit hash, or any other build-related information. We usually only use this for internal builds, however it can be used for public releases as well, if needed.
We use the following formats for build metadata:
- exp: Experimental build: This is usually used for internal builds that are not meant for public release.
- sha: Commit hash: This is used to identify the commit hash of the build.
- build: Build number: This is used to identify the build number of the build.
You can either use all of these formats or only some of them, depending on your requirements. When combining multiple formats, separate them with a dot (.). For example, 1.0.0+exp.sha.5114f85.build.123.
Exceptions for security patches: We use the PATCH version for security patches. However, if the security issue is severe (>= 8.0 in CVSS), we increment the MAJOR version. For example, if the current version is 1.0.0, and a security patch is released, the new version will be 1.0.1. If the security issue is severe, the new version will be 2.0.0. This helps users to quickly identify the severely affeted version and the version with the security patch.

Conventional Commits

Conventional Commits is a specification for adding human and machine readable meaning to commit messages. It is a simple set of rules for creating an explicit commit history. For information, see the Conventional Commits specification.

We follow a superset of the Conventional Commits specification. The advantage of this is that it helps in generating release notes, changelogs, and automating the creation of new releases.

Commit Scope Format

When making commits, please specify a scope for the commit. The scope should be the name of the module or component that you are working on. For example:

feat(kernel): add new feature

In this example, kernel is the module or component that the commit is related to. You might also divide the scope into multiple parts, separated by a colon (:) to indicate submodules or subcomponents. For example:

feat(kernel:core): add new feature

In this example, kernel is the main module and core is a submodule of the kernel module.

Additional commit types

Our superset defines the following additional commit types:

release: This commit type is used for release commits. It is used to indicate that a new version has been released. For example:
```
release: v1.0.0 [skip ci]
```
The [skip ci] tag is used to indicate that this commit should not trigger a CI build.
deps: This commit type is used for dependency updates. It is used to indicate that a dependency has been updated. For example:
```
deps: update dependencies
```
This commit type may have a subject. The subject is usually dev to indicate a development dependency update, or maybe a specific package name to indicate a specific dependency update. For example:
```
deps(dev): update dev dependencies
```
merge: If you perform a merge, use this commit type. When using the git merge command, you can pass the -m option and a commit message as an argument. Sometimes git can choose to not perform a merge commit and instead perform a "fast-forward" merge. In that case, there will be no additional commit, and therefore the message will be ignored. In other cases when Git creates a new commit, the commit message will be used.
Example:
```
git merge feature/new-permission-system -m "merge: feature/new-permission-system branch to main"
```
i18n: This commit type is used when you add translations or make changes that affect the internationalization of the bot.

In addition to the rules described in the original Conventional Commits specification, we also have the following rules:

Always use BREAKING CHANGE in the commit message if there are breaking changes: If you make a change that breaks backward compatibility, always use the BREAKING CHANGE keyword in the commit message and then provide information about the change. This helps users to quickly identify the breaking changes in the release notes. This also helps in identifying the MAJOR version bump in the release notes, whether it is a security patch or a breaking change. For example:
```
feat(kernel:core)!: add new feature
 
BREAKING CHANGE: This commit breaks backward compatibility.
```
The ! symbol is used to indicate that this commit is a starting point of a new major version, according to the Semver specification.
Always use SECURITY in the commit message for security patches: If you make a security patch, always use the SECURITY keyword in the commit message and then provide information about the security issue. This helps users to quickly identify the security patches in the release notes. For example:
```
fix(kernel:core)!: fix security issue
 
SECURITY: This commit fixes a security issue.
```
Always use DEPRECATED in the commit message for deprecated features: If you deprecate a feature, always use the DEPRECATED keyword in the commit message and then provide information about the deprecation. This helps users to quickly identify the deprecated features in the release notes. The commit type should be feat in this case. For example:
```
feat(kernel:core)!: deprecate old feature
 
DEPRECATED: This commit deprecates an old feature.
```
Use the release commit type for release commits: If you are making a release commit, always use the release commit type, as described above.
Use the deps commit type for dependency updates: If you are making a dependency update, always use the deps commit type, as described above.

Branching Strategy

We follow the an extended version of the GitHub Flow workflow. The only main branch is main — this is the branch that is always deployed to production. Notable development works are done in feature branches, which are then merged into the main branch via pull requests. If the feature or fix you're working on is small, you can commit directly to the main branch.

We also have the following additional branches:

Release Branches: We create release branches for each major version. For example, if the current version is 1.0.0, the release branch will be 1.x. This branch is used for bug fixes and security patches for that specific version without merging them into the main branch. Once all the bug fixes and security patches are done, we create a new release from this branch.

After the release reaches its EOL (End of Life), we archive the branch and stop providing support for that version.
Bugfix Branches: We create bugfix branches for working on a notable bug fix or security patch. These branches are created from the main branch and are merged back into the main branch via pull requests. These branches are prefixed by bugfix/.
Feature Branches: We create feature branches for working on new features. These branches are created from the main branch and are merged back into the main branch via pull requests. These branches are prefixed by feature/.

Automation of Releases and Changelog Generation

We use GitHub Actions for automating the release process and generating changelogs. We have a custom GitHub Action that automatically generates changelogs based on the commit messages and creates a new release on GitHub. The action is available on GitHub marketplace: Conventional Release Action.

The action uses the commit messages to generate the changelog and release notes, and then bumps the version number based on the commit messages and the rules of our superset of the Conventional Commits specification and Semver.

Tips to leaverage the action

Forcing pre-release versions: If you want to force a pre-release version, you can use a prerelease specifier in your commit message. For example:
```
 feat(kernel:core): add new feature [prerelease]
```
The identifier must be inside square brackets ([]) and must be one of prerelease, alpha, beta. This will force the action to bump the version to a pre-release version.
Forcing build metadata: If you want to force build metadata, you can use add the Build-metadata footer in your commit message. For example:
```
feat(kernel:core): add new feature
 
Build-metadata: exp.sha.5114f85.build.123
```
This will force the action to add the build metadata to the version.
Forcing a specific version suffix: If you want to force a specific version suffix, you can use the Version-suffix footer in your commit message. For example:
```
feat(kernel:core): add new feature
 
Version-suffix: -alpha.1
```
This will force the action to use the specified version suffix.

Signing off commits and using GPG signatures

We require developers to sign off their commits and optionally use GPG signatures for signing commits. Please note that "signing off" and "GPG signing" are two different things.

Signing off commits: When you make a commit, you must sign off the commit by adding a Signed-off-by line at the end of the commit message. This is usually done by adding Signed-off-by: Your Name <youremail@addr.com>. This is a way to certify that you have the rights to submit the code under the project's license. For example:
```
feat(kernel:core): add new feature
 
Signed-off-by: John Doe <johndoe@acme.com>
```
If you're using the Git CLI, you can add the -s flag to automatically add the Signed-off-by line. For example:
```
git commit -sm "feat(kernel:core): add new feature"
```
This is a good practice to follow, especially when contributing to open source projects.
Using GPG signatures: GPG signatures are used to sign commits and tags. This is a way to certify that the commit or tag was made by you and not by someone else. This is especially useful for verifying the authenticity of commits and tags in open source projects. For more information on how to use GPG signatures with Git, see the GitHub documentation. GitHub shows a "Verified" badge next to commits and tags that are signed with GPG signatures.