Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/macstab/semantic-release-maven-gradle-nodejs-python-git-jq

Docker image with semantic release plus inherited nodejs, git, jq and python tools, java gradle and maven
https://github.com/macstab/semantic-release-maven-gradle-nodejs-python-git-jq

docker gitops image infrastructure

Last synced: 2 months ago
JSON representation

Docker image with semantic release plus inherited nodejs, git, jq and python tools, java gradle and maven

Awesome Lists containing this project

README 

          
# Chapter 1: Introduction to the Docker Image



## Purpose and General Description



The Docker image serves as a foundational platform for projects utilizing semantic-release for automated version management and releases. This image is specifically tailored to support various programming environments, including JavaScript, Java (with Maven and Gradle), and Python, making it a versatile choice for a wide range of development and release tasks.



## Base Image and its Significance



The base image, `macstab/node-python-git-jq-bookworm:latest`, is a meticulously chosen image that combines Node.js, Python, Git, and JQ on a Debian Bookworm distribution. This blend is particularly beneficial for projects that necessitate the use of multiple programming languages and tools throughout their build and release process. The choice of this base image underscores the image's flexibility and readiness to handle diverse development requirements.



## Custom Configurations and Environment Variables



One of the key features of this Docker image is its support for custom configurations through the environment variable `SEMANTIC_RELEASE_CONFIG`. This allows for various project environments to be easily managed and configured. The image supports several predefined configurations, specifically tailored for different environments such as JavaScript, Maven, and Python.



These configurations are accessible and modifiable, providing users with the flexibility to adapt the image to their specific project needs. This capability significantly simplifies the process of setting up and managing project-specific release workflows.



---



# Chapter 2: Dependencies, Packages, and Versions



## Overview of the Base Image Components



The base image `macstab/node-python-git-jq-bookworm:latest` is built on Debian Bookworm. It includes several key components crucial for development and deployment:



### Core Components



| Component | Version | Description                                                           |

|-----------|---------|-----------------------------------------------------------------------|

| Node.js   | 21.4.0  | JavaScript runtime environment. [Node.js](https://nodejs.org/)        |

| Python    | 3.12.0  | Programming language for scripting. [Python](https://www.python.org/) |

| Git       | 2.42.0  | Version control system. [Git](https://git-scm.com/)                   |

| JQ        | 1.8     | Command-line JSON processor. [JQ](https://stedolan.github.io/jq/)     |



*Note: Replace `[version]` with the specific versions included in the Docker image.*



## Additional Software and Tools



The image also includes additional tools to support a wide range of development tasks:



### Additional Tools



| Tool      | Version | Description                                                                 |

|-----------|---------|-----------------------------------------------------------------------------|

| Java      | 21      | Programming language for Java-based projects. [Java](https://www.java.com/) |

| Maven     | 3.9.6   | Build automation tool for Java projects. [Maven](https://maven.apache.org/) |

| Gradle    | 8.5     | Build tool for Java projects. [Gradle](https://gradle.org/)                 |



*Note: Replace `[version]` with the actual versions included in the Docker image.*



## Version Management



Proper version management is essential for the stability and reliability of the development environment. This section outlines the strategies for managing and updating the versions of dependencies and tools within the Docker image.



---



# Chapter 3: Installed Tools Overview



This chapter provides a comprehensive overview of the key tools installed in the Docker image, highlighting their roles, versions, and significance in the development and release process.



## Semantic Release



Semantic Release automates the versioning and package publishing process based on semantic versioning principles. It streamlines the release process, reduces human error, and ensures consistent version management.



### Core Features



- **Automated Version Management**: Determines the next version number based on commit messages.

- **Changelog Generation**: Automatically generates and updates the changelog with release notes.

- **Package Publishing**: Publishes the package to the respective package registry.



### Version



| Tool            | Version |

|-----------------|---------|

| Semantic Release | 22.0.10 |



*Semantic Release [official documentation](https://semantic-release.gitbook.io/semantic-release/).*



## Java, Gradle, and Maven



Java, along with Gradle and Maven, are essential for building and managing Java-based projects.



### Versions



| Tool  | Version |

|-------|---------|

| Java  | 21      |

| Gradle| 8.5     |

| Maven | 3.9.6   |



*Java: [official site](https://www.java.com/)*  

*Gradle: [official site](https://gradle.org/)*  

*Maven: [official site](https://maven.apache.org/)*



## Python



Python is a versatile programming language used in a wide range of applications, from web development to data analysis.



### Version



| Tool  | Version |

|-------|---------|

| Python| [version] |



*Python [official site](https://www.python.org/).*



## Node.js



Node.js is a JavaScript runtime built on Chrome's V8 JavaScript engine, crucial for running JavaScript on the server side.



### Version



| Tool  | Version |

|-------|---------|

| Node.js | [version] |



*Node.js [official site](https://nodejs.org/).*



## Tool Version Management



Proper management of tool versions is critical for ensuring consistency and reliability in the development process. This section should elaborate on strategies employed in the Docker image for managing and updating these tools.



---



# Chapter 4: Detailed Guide to Semantic-Release



Semantic-Release is a fully automated version management and package publishing tool that follows the semantic versioning (SemVer) guidelines. This chapter provides an in-depth look at Semantic-Release, covering its core functionality, modules, plugins, and how to effectively use it in various development scenarios.



## Core Functionality of Semantic-Release



Semantic-Release automates the versioning process based on commit messages, making it a vital tool for continuous integration and continuous deployment (CI/CD) pipelines. It simplifies the release process, ensuring consistency and efficiency.



### Automated Version Management



Semantic-Release analyzes commit messages to determine the type of version change (major, minor, or patch). This process relies on a structured format for commit messages, typically following the Conventional Commits standard.



### Changelog Generation



Automatically generating a changelog with each release is a key feature of Semantic-Release. This ensures that all changes, features, and fixes are documented and easily accessible.



### Package Publishing



Semantic-Release integrates with various package registries (like npm, PyPI, Maven, etc.) to automate the release and publishing of packages. This seamless integration is crucial for maintaining a smooth and consistent release cycle.



## Modules and Plugins Overview



Semantic-Release is highly customizable and extensible through its plugin architecture. This section explores the various plugins and modules available, detailing their functionalities and use cases.



### Default Plugins



- **@semantic-release/commit-analyzer**: Analyzes commit messages to determine the type of release.

- **@semantic-release/release-notes-generator**: Generates release notes based on commit messages.

- **@semantic-release/changelog**: Manages the changelog file.

- **@semantic-release/npm**: Publishes the package to npm.

- **@semantic-release/github**: Integrates with GitHub for release management.



### Additional Plugins



There are numerous other plugins available for Semantic-Release, catering to specific needs and integrations. This section will provide an overview of popular plugins and their functionalities.



## Configuration and Customization Options



Semantic-Release is highly configurable, allowing for customization to fit specific project requirements. This section delves into the configuration options, environment variables, and how to tailor Semantic-Release for different project environments.



### Basic Configuration



A basic Semantic-Release configuration involves setting up a `.releaserc` file with the necessary plugins and their configurations. This section will provide a step-by-step guide to creating a basic configuration.



### Advanced Customizations



For complex projects, Semantic-Release can be customized extensively. This includes setting up conditional releases, multi-environment setups, and integrating with CI/CD pipelines. Advanced configurations and examples will be provided in this section.



## Best Practices for Using Semantic-Release



Implementing Semantic-Release effectively requires adherence to certain best practices. This section outlines these practices, such as structured commit messages, version management strategies, and maintaining release consistency.



### Commit Message Guidelines



Following a structured format like Conventional Commits is essential for the effective functioning of Semantic-Release. This subsection provides guidelines and examples for writing proper commit messages.



### Integration with CI/CD Pipelines



Semantic-Release shines in a CI/CD setup. This subsection provides insights on integrating Semantic-Release with popular CI/CD tools like Jenkins, Travis CI, and GitHub Actions.



## Troubleshooting Common Issues



Despite its automation, issues can arise while using Semantic-Release. This section addresses common problems and their solutions, providing a valuable resource for troubleshooting.



### Issue 1: XYZ



Description and solution for a common issue faced by users of Semantic-Release.



### Issue 2: ABC



Another common issue and its resolution.



*Note: Expand each section with specific details, examples, and additional insights to fully cover the aspects of Semantic-Release. Include screenshots, code snippets, and real-world scenarios for a comprehensive guide.*



---



# Chapter 5: Detailed Guide to Semantic-Release



Semantic-Release automates the versioning and package publishing process based on semantic versioning principles. This chapter focuses on the plugins installed in the Docker image, their functionalities, configuration options, and links to their documentation and codebase. Additionally, it describes the four predefined configurations for Gradle, Maven, Node.js, and Poetry.



## Installed Semantic-Release Plugins and Configurations



Each plugin in Semantic-Release serves a specific purpose in the release automation process. Below are the plugins with example configurations:



### @semantic-release/git



- **Functionality**: Handles Git operations, such as committing files, creating tags, and pushing to the repository.

- **Example Configuration**:

    ```json

    {

    "path": "@semantic-release/git",

    "assets": ["CHANGELOG.md", "package.json"],

    "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"

    }

    ```

- **Documentation**: [Git plugin documentation](https://github.com/semantic-release/git)



### @semantic-release/changelog



- **Functionality**: Manages the changelog file, updating it with each release.

- **Example Configuration**:

   ```json

      {

      "path": "@semantic-release/changelog",

      "changelogFile": "CHANGELOG.md"

      }

    ```

- **Documentation**: [Changelog plugin documentation](https://github.com/semantic-release/changelog)



### semantic-release/release-notes-generator

- **Functionality**: Generates release notes based on commit messages.

- **Example Configuration**:

  ```json

    {

    "path": "semantic-release/release-notes-generator",

    "preset": "angular"

    }

  ```

- **Documentation**: [Release Notes Generator documentation](https://github.com/semantic-release/release-notes-generator)



### @semantic-release/exec

- **Functionality**: Executes custom shell commands during the release process.

- **Example Configuration**:

  ```json

   {

    "path": "@semantic-release/exec",

    "cmd": "./your-custom-script.sh"

    }

  ```

- **Documentation**: [Exec plugin documentation](https://github.com/semantic-release/exec)



### semantic-release/github

- **Functionality**: Manages GitHub releases, including creating release notes and uploading assets.

- **Example Configuration**:

  ```json

    {

    "path": "semantic-release/github",

    "assets": ["dist/*.zip"]

    }

  ```

- **Documentation**: [GitHub plugin documentation](https://github.com/semantic-release/github)



### semantic-release-maven

- **Functionality**: Automates the release process for Maven projects, updating `pom.xml` with the new version.

- **Example Configuration**:

  ```json

    {

    "path": "semantic-release-maven",

    "mavenCmd": "mvn"

    }

  ```

- **Documentation**: [Maven plugin documentation](https://github.com/semantic-release/maven)



### semantic-release-gradle

- **Functionality**: Integrates Semantic-Release with Gradle, updating project version in Gradle files.

- **Example Configuration**:

    ```json

        {

        "path": "semantic-release-gradle",

        "gradleCmd": "gradle"

        }

    ```

- **Documentation**: [Gradle plugin documentation](https://github.com/semantic-release/gradle)



### semantic-release-pypi

- **Functionality**: Publishes Python packages to PyPI.

- **Example Configuration**:

  ```json

  {

  "path": "semantic-release-pypi",

  "pypiUpload": true

  }

  ```

- **Documentation**: [PyPI plugin documentation](https://github.com/semantic-release/pypi)



### @semantic-release/commit-analyzer

- **Functionality**: Analyzes commit messages to determine the next release version.

- **Example Configuration**:

  ```jso

  {

    "path": "@semantic-release/commit-analyzer",

    "preset": "angular"

    }

  ```

- **Documentation**: [Commit Analyzer documentation](https://github.com/semantic-release/commit-analyzer)



### @saithodev/semantic-release-backmerge

- **Functionality**: Automates the process of back-merging release changes into other branches.

- **Example Configuration**:

  ```json

  {

    "path": "@saithodev/semantic-release-backmerge",

    "branchName": "develop"

    }

  ```

- **Documentation**: [Backmerge plugin documentation](https://github.com/saithodev/semantic-release-backmerge)



### semantic-release-license

- **Functionality**: Manages the project's license file, ensuring it's up to date with each release.

- **Example Configuration**:

  ```json

  {

    "path": "semantic-release-license",

    "licensePath": "./LICENSE"

    }

  ```

- **Documentation**: [License plugin documentation](https://github.com/semantic-release/license)



---



# Chapter 6: Utilizing Predefined Semantic-Release Profiles



This chapter explains how to use the four predefined Semantic-Release configurations for Gradle, Maven, JavaScript, and Python projects. The configurations can be controlled by either setting an environment variable or using command-line arguments in the Docker image.



## Selecting Configurations



There are two primary ways to select a specific Semantic-Release configuration:



1. **Environment Variable**: Set the `SEMANTIC_RELEASE_CONFIG` environment variable in the Docker image. The default is `/configs/.releaserc-js.json`.

2. **Command Line Argument**: Use the `--config` argument with the Semantic-Release executable from the Docker image. For example, `semantic-release --config /configs/.releaserc-gradle.json`.



## Profile Overviews and Implementation



Each profile is tailored to suit the specific needs of different development environments. Let's delve into what each profile does and how to implement them.



### Gradle Profile



- **Overview**: This profile is configured for projects using Gradle. It includes rules and plugins suited for managing and releasing Java applications built with Gradle.

- **Key Features**: Commit message analysis, changelog generation, version management tailored for Gradle.

- **Example Usage**:

  ```dockerfile

    SEMANTIC_RELEASE_CONFIG=/configs/.releaserc-gradle.json

  ```



### Maven Profile



- **Overview**: Tailored for Maven projects, this profile automates versioning and releasing in the Maven ecosystem.

- **Key Features**: Integration with Maven's lifecycle, commit analysis, and Maven-specific release processes.

- **Example Usage**:

  ```shell

        docker run -v "$(pwd)":/workspace --platform linux/amd64 macstab/semantic-release-maven-gradle-nodejs-python-git-jq:1.1.1 /bin/bash -c "cp /configs/.releaserc-maven.json .releaserc && cd /workspace && semantic-release"



  ```



### JavaScript Profile



- **Overview**: Designed for JavaScript-based projects, especially those managed with npm or yarn.

- **Key Features**: NPM publishing, commit message analysis, and automated release notes generation.

- **Example Usage**:

  ```shell

        docker run -v "$(pwd)":/workspace --platform linux/amd64 macstab/semantic-release-maven-gradle-nodejs-python-git-jq:1.1.1 /bin/bash -c "cp /configs/.releaserc-js.json .releaserc && cd /workspace && semantic-release"



  ```



### Python Profile



- **Overview**: Configured for Python projects, particularly those using Poetry for package management.

- **Key Features**: Supports Python package versioning, PyPI publishing, and Python-specific release workflows.

- **Example Usage**:

  ```shell

        docker run -v "$(pwd)":/workspace --platform linux/amd64 macstab/semantic-release-maven-gradle-nodejs-python-git-jq:1.1.1 /bin/bash -c "cp /configs/.releaserc-python.json .releaserc && cd /workspace && semantic-release"



  ```  



### Profile for no build tools (i.e. docker images, configurations, infrastructure as code, etc.)



- **Overview**: Configured for no build tool projects.

- **Key Features**: Supports Releases and tags.

- **Comment**: The package json is just forconvinienve to run semantic-release. It is not used for release.

- **Example Usage**:

  ```shell

    docker run -v "$(pwd)":/workspace --platform linux/amd64 macstab/semantic-release-maven-gradle-nodejs-python-git-jq:1.1.1 /bin/bash -c "cp /configs/.releaserc-docker.json .releaserc && cd /workspace && semantic-release"

  ```  



This chapter provides a guide on how to use the predefined Semantic-Release profiles for different development environments and includes basic usage examples. You can further expand each section with more detailed information, specific customization guidelines, and additional examples as needed.