README

Automatically generate a changelog for your users inside your Laravel App based on your commit descriptions.

Introduction

When building a web project, it's important to let your users know what changed in each release, or even as soon as a bug is fixed. You might do that through a blog post, or on social media, but it's still a manual process.

This package will automatically generate a changelog based on your commit descriptions. It will fetch the commit history from your repository and store the messages from your commit descriptions in a database table.

You can then display the changelog in your app, or even send it to your users via email.

Installation

You can install the package via composer:

composer require mydnic/changelog-commit-for-laravel

You can publish and run the migrations with:

php artisan vendor:publish --tag="changelog-commit-for-laravel-migrations"
php artisan migrate

You can publish the config file with:

php artisan vendor:publish --tag="changelog-commit-for-laravel-config"

This is the contents of the published config file:

return [
    /**
     * The name of the table to store the changelog in.
     */
    'table_name' => 'changelogs',

    /**
     * The GitHub access token to use to fetch the commit history.
     */
    'github_access_token' => env('GITHUB_ACCESS_TOKEN'),

    /**
     * The GitHub repositories to fetch the commit history from.
     */
    'github_repositories' => [
        'mydnic/changelog-commit-for-laravel', // change me
        // other repositories if you want to fetch the commit history from multiple repositories
    ],
];

Usage

Once the package is installed on your project, you should add the changelod:fetch command to your deployment process.

Now, every time your application is deployed, the changelog will be updated with the latest commit messages.

Write your commit messages

Here's an example of a commit message:

fix: issue with authentication

> You can now login without any issue
> Enjoy!

As you can see, the commit message is composed of several lines. The first line is your usual commit message. The other lines can be used to add more details about the commit.

But only the other lines starting with > will be used to generate the changelog.

Generate the changelog

After you've pushed your commits, you can run the following command to fetch the commit history. Or you can add this command to your deployment process so you don't have to run it manually.

php artisan changelog:fetch

This will fetch the commit history from your repository and store the messages (all lines starting with >) from your commit descriptions in a database table.

Showing the changelog

You can then display the changelog in your app, or even send it to your users via email.

Here's an example of how to display the changelog in your app:

Use the Changelog model to fetch the changelog entries in your application.

use Mydnic\ChangelogCommitForLaravel\Models\Changelog;

$changelogs = Changelog::latest('date')->paginate(50);

return view('changelog', compact('changelogs'));
// or return JSON response
return response()->json($changelogs);

Front End Examples

Please submit more examples if you have any!

VueJS Component

<template>
    <div>
        <div
            v-for="date in Object.keys(groupedChangelog)"
            :key="date"
        >
            <h2 class="text-lg font-semibold text-gray-800 mt-5 mb-1 capitalize">
                {{ $filters.format(date, 'dddd DD MMM YYYY') }}
            </h2>
            <ul class="list-disc pl-4 text-gray-600 space-y-1">
                <li
                    v-for="item in groupedChangelog[date]"
                    :key="item.message"
                    class="text-sm"
                >
                    {{ item.message }}
                </li>
            </ul>
        </div>

        <div
            v-if="pagination.last_page > pagination.current_page"
            class="text-center mt-10"
        >
            <button
                class="btn btn-sm"
                :class="{ loading: isLoading }"
                :disabled="isLoading"
                @click="loadMore"
            >
                Load more...
            </button>
        </div>
    </div>
</template>

<script>
import { defineComponent } from 'vue'

export default defineComponent({
    data () {
        return {
            changelog: [],
            pagination: {}
        }
    },

    computed: {
        groupedChangelog () {
            return this.changelog.reduce((acc, item) => {
                const key = item.date
                if (!acc[key]) {
                    acc[key] = []
                }
                acc[key].push(item)
                return acc
            }, {})
        }
    },

    created () {
        this.getChangelog()
    },

    methods: {
        getChangelog (page = 1) {
            fetch('https://your-app.example/api/changelog?page=' + page)
                .then(response => response.json())
                .then((data) => {
                    this.changelog = [...this.changelog, ...data.data]
                    this.pagination = {
                        current_page: data.current_page,
                        last_page: data.last_page
                    }
                })
        },

        loadMore () {
            this.getChangelog(this.pagination.current_page + 1)
        }
    }
})
</script>

Laravel Blade

class ChangelogController
{
    public function __invoke()
    {
        $changelog = DB::table(config('changelog-commit-for-laravel.table_name'))
            ->select('message', 'date')
            ->orderBy('date', 'desc')
            ->paginate(10);

        // Group by date
        $groupedChangelog = $changelog->getCollection()->groupBy('date');

        return view('changelog', [
            'groupedChangelog' => $groupedChangelog,
            'pagination' => $changelog // Pass pagination object
        ]);
    }
}

<div>
    @foreach ($groupedChangelog as $date => $items)
        <h2 class="text-lg font-semibold text-gray-800 mt-5 mb-1 capitalize">
            {{ \Carbon\Carbon::parse($date)->translatedFormat('l d M Y') }}
        </h2>
        <ul class="list-disc pl-4 text-gray-600 space-y-1">
            @foreach ($items as $item)
                <li class="text-sm">
                    {{ $item->message }}
                </li>
            @endforeach
        </ul>
    @endforeach

    {{-- Laravel Pagination Links --}}
    <div class="mt-10">
        {{ $pagination->links() }}
    </div>
</div>

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

mydnic / changelog-commit-for-laravel

Maintainers

Details