Skip to content
Snippets Groups Projects
Commit 45f58e12 authored by Benguria Elguezabal, Gorka's avatar Benguria Elguezabal, Gorka
Browse files

adds semantic versioning ci cd

parents
No related branches found
No related tags found
No related merge requests found
LICENSE 0 → 100644
MIT License
Copyright (c) 2024 Tecnalia
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
# Emerald Caas Framework Contribution Guidelines
This repository contains Contribution Guidelines for Caas Framework in emerald project.
## Table of contents
- [Table of contents](#table-of-contents)
- [Description](#description)
- [Usage](#usage)
- [Support](#support)
- [Roadmap](#roadmap)
- [Contributing](#contributing)
- [Authors and acknowledgment](#authors-and-acknowledgment)
- [License](#license)
- [Project status](#project-status)
## Description
This repository contains diferent utility guidelines on how to contribute to the Emerald Caas Framework. The guidelines are divided into different sections, each one with a specific purpose.
- [Enroll](https://git.code.tecnalia.com/emerald/public/enroll/-/blob/master/README.md) how to join to the repository for contributions.
- [Component Development](./component_development.md): Contains the guidelines for developing a new component for the Caas Framework.
- [Component Integration](./component_integration.md): Contains the guidelines for integrating a new component into the Caas Framework.
- [Component Validation](./component_validation.md): Contains the guidelines for validating a new component for the Caas Framework.
- [Keycloak Integration](./keycloak_integration.md): Contains the guidelines for integrating Keycloak into the components of the Caas Framework.
- [Component Update](./component_update.md): Contains the guidelines for updating a component of the Caas Framework.
- [Component Troubleshooting](./component_troubleshooting.md): Contains the guidelines for troubleshooting a component of the Caas Framework.
- [Semantic Versioning with Gitlab CI/CD](./semantic_versioning_ci_cd.md): Contains the guidelines for versioning the components of the Caas Framework.
- [Component Publish with Gitlab CI/CD](./component_publish_ci_cd.md): Contains the guidelines for setting up the CI/CD pipeline for a component image publishing in gitlab.
Version: 1.0.0
## Support
If you require support for improving the template add an [issue](../../../-/issues) to the template and contact the [Owners/Maintainers](../-/project_members?sort=access_level_desc) of the repo.
Note: remember to change this section to match the support options for your project.
## Roadmap
No future plans for this project appart from improving the template based on feedback.
## Contributing
In order to contribute to the project, you can [fork](../../../-/forks/new) the repository and create a merge request. The merge request will be reviewed by the project maintainers and if it is accepted it will be merged into the main branch.
## Authors and acknowledgment
This project was developed by [Tecnalia](https://www.tecnalia.com/).
Thanks to:
- [makeareadme.com](https://www.makeareadme.com/#suggestions-for-a-good-readme) for this template.
- [Emerald Project](https://www.emerald-he.eu/) for resources and inspiration.
- [To be Continous](https://to-be-continuous.gitlab.io/doc/) for the CI/CD components.
- [Gitlab CI/CD](https://docs.gitlab.com/ee/ci/) for the CI/CD documentation.
## License
Read the [license file](../../../LICENSE) for more information.
## Project status
The project is in a stable state and is not actively being developed.
# Semantic Versioning with Gitlab CI/CD
This document contains the guidelines for integration and usage of the semantic versioning with Gitlab CI/CD components for versioning the outcomes of the Emerald Project.
## Table of contents
## Semantic Versioning
Semantic versioning is a versioning system that allows to define the version of a software component based on the changes that have been made to it. The version number is composed of three numbers separated by dots: `MAJOR.MINOR.PATCH`. The version number is increased based on the following rules:
- `MAJOR` version is increased when incompatible changes are made to the software component.
- `MINOR` version is increased when new features are added to the software component in a backwards-compatible manner.
- `PATCH` version is increased when backwards-compatible bug fixes are made to the software component.
[semver.org](https://semver.org/) provides a detailed explanation of the semantic versioning system.
## Semantic Release CI/CD
[Semantic Release](https://semantic-release.gitbook.io/semantic-release/) is a **tool** that automates the versioning and release of software components. It **uses the commit messages to determine the type of changes** that have been made to the software component and automatically increases the version number based on the changes that have been made.
It offloads the responsibility of versioning and releasing software components from the developers, allowing them to focus on writing code and making changes to the software component. Managing the versioning and releasing of software components can be a time-consuming and error-prone process, as it may involve manually updating the version number in multiple places, creating release notes, and publishing the software component in different places.
Semantic Release automates this process by analyzing the commit messages that have been made to the software component and determining the type of changes that have been made. It then increases the version number based on the changes that have been made and creates release notes that describe the changes that have been made. It also publishes the software component to different places, such as a package registry or a container registry.
## Semantic Release with Gitlab CI/CD
We have integrated the Semantic Release tool with Gitlab CI/CD to automate the versioning and releasing of software components within the Emerald gitlab framework. To achieve this, we have adapted the [TBC](https://to-be-continuous.gitlab.io/) CI/CD pipeline to include the Semantic Release tool in our gitlab instance. The adapted components are available in our CI/CD Catalogue in the Component [Semantic Release](https://git.code.tecnalia.com/explore/catalog/smartdatalab/public/ci-cd-components/semantic-release).
## Usage
The usage of the Semantic Release CI/CD component involves two main steps: Installation and Releasing.
### Installation
To install the Semantic Release CI/CD component, you need to add the following configuration to your `.gitlab-ci.yml` file:
```yaml
- component: git.code.tecnalia.com/smartdatalab/public/ci-cd-components/semantic-release/gitlab-ci-semrel@master
inputs:
semantic-release-job-tags: ["docker"]
auto-release-enabled: true
branches-ref: "/^(master|main)$/"
```
Appart from the configuration in the .gitlab-ci.yml file, you can also add a `.releaserc.yaml` file to the root of your repository if you require a specific configuration for the semantic release. The `.releaserc.yaml` file is a JSON file that contains the configuration for the semantic release tool. The configuration file can be used to specify the plugins that should be used by the semantic release tool, the branches that should be released, and other options that are available. The configuration file is optional, and if it is not present, the semantic release tool will use the default configuration. For example, if you want to include CHANGELOG generation in the release process, you can add the following configuration to the `.releaserc.yaml` file:
```yaml
plugins:
- '@semantic-release/commit-analyzer'
- '@semantic-release/release-notes-generator'
- '@semantic-release/gitlab'
# generates the CHANGELOG.md
- '@semantic-release/changelog'
- - '@semantic-release/git'
- assets:
- 'CHANGELOG.md'
# the commit MUST trigger a pipeline on tag (to perform publish jobs)
# can be skipped on prod branch
message: 'chore(semantic-release): release ${nextRelease.version} - [ci skip on prod]'
branches:
- main
- master
tagFormat: '${version}'
```
Besides, the installation of the Semantic Release CI/CD component requires some additional settings to be performed in the gitlab project settings. The following settings are required to be set in the gitlab project settings:
- Generate a project access token with the `api` and `write_repository` scopes. The token should be stored in the gitlab CI/CD settings as a secret variable with the name `GITLAB_TOKEN` and it requires an account with the `Maintainer` role in the project. The variable can be set as `protected` and `masked`, but this is optional. The `protected` requires to work with the `protected branches` settings in the project.
- Depending on the release custom configuration it may be problematic to use the protected tags feature. In this case, the `protected tags` feature should be disabled in the project settings. To set the protected tags feature `Maintainer` role is required in the project.
- Another good to have setting is to disable the the "Squash commits" feature in the project settings. We use to configure it in an `Allow` mode. When the commits are squashed, the semantic release tool may not be able to determine the type of changes that have been made to the software component. To set the "Squash commits" feature `Maintainer` role is required in the project.
To see the full configuration, you can check a current instalations in:
- [Architecture and Data Modelling](https://git.code.tecnalia.com/emerald/private/architecture-and-data-modelling) repository. There you can check the [`.gitlab-ci.yml`](https://git.code.tecnalia.com/emerald/private/architecture-and-data-modelling/-/blob/main/.gitlab-ci.yml) file in the root of the repository.
- [RCM - Repository of Controls and Metrics](https://git.code.tecnalia.com/emerald/private/standards-and-data/rcm) repository. There you can check the [`.releaserc.yaml`](https://git.code.tecnalia.com/emerald/private/standards-and-data/rcm/-/blob/main/.releaserc.yaml) file in the root of the repository. To see a more complex configuration.
### Releasing
In this section we will explain how to trigger a new release of your software component using the Semantic Release CI/CD component. The release process is triggered by creating a commit with a specific message that describes the type of changes that have been made to the software component. The commit message should follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification, which defines a set of rules for writing commit messages that describe the type of changes that have been made to the software component.
- fix: this is the most common type of change, and it is used when a bug fix has been made to the software component. The fix type is used when a backwards-compatible bug fix has been made to the software component. For example, if a bug has been fixed in the software component, the commit message should start with `fix:` followed by a brief description of the bug that has been fixed.\
this will trigger a patch release of the software component, increasing the `PATCH` version number by one. The new version number will be `MAJOR.MINOR.PATCH+1`. For example, if the current version number is `1.0.0`, the new version number will be `1.0.1`.\
Example:
```bash
git commit -m "fix: fixed a bug in the software component"
```
- feat: this type of change is used when a new feature has been added to the software component. The feat type is used when a backwards-compatible new feature has been added to the software component. For example, if a new feature has been added to the software component, the commit message should start with `feat:` followed by a brief description of the new feature that has been added.\
this will trigger a minor release of the software component, increasing the `MINOR` version number by one. The new version number will be `MAJOR.MINOR+1.0`. For example, if the current version number is `1.0.0`, the new version number will be `1.1.0`.\
Example:
```bash
git commit -m "feat: added a new feature to the software component"
```
- BREAKING CHANGE: this type of change is used when an incompatible change has been made to the software component. The BREAKING CHANGE type is used when a backwards-incompatible change has been made to the software component. For example, if an incompatible change has been made to the software component, the commit message should start with `BREAKING CHANGE:` followed by a brief description of the incompatible change that has been made.\
this will trigger a major release of the software component, increasing the `MAJOR` version number by one. The new version number will be `MAJOR+1.0.0`. For example, if the current version number is `1.0.0`, the new version number will be `2.0.0`.\
Example:
```bash
git commit -m "BREAKING CHANGE: made an incompatible change to the software component"
```
NOTE: When merging the squashed commit option should be disabled. The squashed commits remove the commit messages and the semantic release tool will not be able to determine the type of changes that have been made to the software component.
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment