Implement Changelog Generation Using Conventional Commits

[kaszabimre]

Follow the Contribution Guidelines:

• Before contributing, make sure to check the Contributing section in the root README.md file for more information on how to contribute to this project.

Goal

Set up automatic changelog generation for the project using conventional-changelog-cli and a custom configuration file. This will standardize release notes and provide a clear log of changes for each version.

Files Provided

The following files will be used to generate changelogs:

1. scripts/changelog-config.cjs:
   This file contains the configuration for conventional-changelog-cli, transforming the commit types (e.g., 'feat', 'fix') into human-readable sections (e.g., 'Features', 'Bug Fixes').

   module.exports = {
     writerOpts: {
       transform: (commit, context) => {
         const newCommit = { ...commit };
   
         let type = newCommit.type;
         if (type === 'feat') {
           type = 'Features';
         } else if (type === 'fix') {
           type = 'Bug Fixes';
         }  else if (type === 'chore') {
           type = 'Improvements';
         } else if (type === 'refactor') {
           type = 'Code Refactoring';
         } else if (type === 'perf') {
           type = 'Performance Improvements';
         } else {
           return;
         }
   
         newCommit.type = type;
   
         if (newCommit.scope === '*') {
           newCommit.scope = '';
         }
   
         if (typeof newCommit.hash === 'string') {
           newCommit.hash = newCommit.hash.substring(0, 7);
         }
   
         return newCommit;
       },
       headerPartial: `## ${process.env.VERSION} ({{date}})`,
       commitPartial: `* {{subject}} - [({{hash}})](https://github.com/kaszabimre/EAPlayers/commit/{{hash}})`
     },
     preset: 'angular',
     releaseCount: 0,
   };

2. scripts/generate-changelog.js:
   This script reads version information from the gradle.properties file and uses the conventional-changelog-cli to generate a changelog.

   const fs = require('fs');
   const { execSync } = require('child_process');
   const path = require('path');
   
   // Path to your gradle.properties file
   const gradlePropertiesPath = path.join(__dirname, '../gradle.properties');
   console.log(`Reading gradle.properties from: ${gradlePropertiesPath}`);
   
   try {
      // Read gradle.properties file
      const gradlePropertiesContent = fs.readFileSync(gradlePropertiesPath, 'utf8');
      const versionCodeMatch = gradlePropertiesContent.match(/io\.imrekaszab\.eaplayers\.build\.version\.code=(\d+)/);
      const versionNameMatch = gradlePropertiesContent.match(/io\.imrekaszab\.eaplayers\.build\.version\.name=([^]+)/);
   
      if (!versionCodeMatch || !versionNameMatch) {
         throw new Error('Version information not found in gradle.properties');
      }
   
      const currentVersionCode = versionCodeMatch[1];
      const currentVersionName = versionNameMatch[1];
      console.log(`Current version code: ${currentVersionCode}`);
      console.log(`Current version name: ${currentVersionName}`);
   
      // Set the environment variable for the version
      process.env.VERSION = currentVersionName;
   
      // Generate changelog using conventional-changelog
      const command = `conventional-changelog -p angular -i CHANGELOG.md -s --config scripts/changelog-config.cjs`;
      execSync(command, { stdio: 'inherit' });
   } catch (error) {
      console.error(`Failed to generate changelog: ${error.message}`);
      process.exit(1);
   }

Steps

1. Update gradle.properties:

   • Ensure the gradle.properties file contains the correct version information.
   • Add the following lines to gradle.properties:

     com.imrekaszab.eaplayers.build.version.code=1
     com.imrekaszab.eaplayers.build.version.name=0.1.1

2. Run the Changelog Generation Script:

   • In your terminal, navigate to the root of the project and run the generate-changelog.js script to generate a changelog based on the conventional commit history.

   Example:

   node scripts/generate-changelog.js

   This will generate or update the CHANGELOG.md file with entries based on the commit history, grouped by categories such as Features, Bug Fixes, and Code Refactoring.

3. Modify the README.md to Include Changelog Instructions:

   • Update the README.md file to include a section on how to generate the changelog for the project.

   Example:

   ### Generating Changelog
   
   To generate the changelog for this project, follow these steps:
   
   1. **Install Node.js and npm:**
      - If you don't have Node.js and npm installed, you can install them using Homebrew:
        ```bash
        brew install node
        ```
   
   2. **Install `conventional-changelog-cli`:**
      - Open a terminal and run the following command to install the `conventional-changelog-cli` globally:
        ```bash
        npm install -g conventional-changelog-cli
        ```
   
   3. **Run the changelog generation script:**
      - In your terminal, navigate to the root directory of your project and run:
        ```bash
        node scripts/generate-changelog.js
        ```
   
   This will read the version information from the `gradle.properties` file and generate the changelog based on the conventional commits using the configuration file located at `scripts/changelog-config.cjs`.

4. Tag the Release in main:

   • After generating the changelog and ensuring everything is correct, create a version tag in the main branch. The tag should follow the version number in gradle.properties, prefixed with a v.

   Example:

   git tag v0.1.1
   git push origin v0.1.1

5. Validate Changelog Generation:

   • Ensure that after running the script, the CHANGELOG.md file is correctly generated or updated with the latest commit history.
   • Verify that the commit types are transformed according to the configuration in changelog-config.cjs.

Outcome

Once this task is complete, the project will have an automated changelog generation process based on conventional commits. This will standardize release notes and make it easier to track the history of changes between releases.