Creating a changelog

Work in Progress

I’m creating a changelog which tracks git history for the generated output of this site.

The reason I’m doing this is twofold. First, I’ve been meaning to do this for a while because I want to provide a feed of edits, not just new articles. Second, more immediately, I’ve set myself a challenge to publish words every day. I want to have a way to track statistics: words added and removed.

Steps

Here’s what I’m doing.

1. create a git repository in the ignored _site directory

The main git repo ignores the _site directory containing the generated output. I created a git repo in it, with the git dir elsewhere, and I set an alias to run git with that as the working directory:

alias --save pubgit="git --git-dir=/path/to/git/dir/elsewhere \\
--work-tree=/path/to/this/repo/_site"

Now I can run pubgit from anywhere with all the usual git commands, and they will be applied as if I was in that directory.

2. Generate the changes with a git command

This is where I’m at right now. I’m evaluating various ways of doing this: should I roll my own little system, or use an existing fully-featured tool?

If I’m in my site’s src directory, I can run pubgit log --name-status and get a commit log with the commit message and metadata, and a line for each file that was changed with the status codes M(odiied), A(dded), D(eleted). I could redirect this to a file in the source repository, e.g. changelog.txt.

Here’s the log for the main source repository since I don’t have any history for the output repository yet:

$ git log --name-status 
commit 624bbf3eb634660fce145f49bf88dd2844f3bca7 (HEAD -> master, origin/master, origin/HEAD)
Author: Hans Fast <hans@hansfast.net>
Date:   Tue Sep 24 15:21:47 2024 +0200

    typo

M       src/notes/for-now-I-am-publishing-mechanism.md

commit 63002a57ece75de4a76e357f520c6ed68c02f9af
Author: Hans Fast <hans@hansfast.net>
Date:   Tue Sep 24 15:11:07 2024 +0200

    add note: publishing mechanism

A       src/notes/for-now-I-am-publishing-mechanism.md
[truncated]

I could also get a diff between two commits with this information. For example, I could do a diff from the last release tag to the current work tree with: git diff --name-status COMMIT_ID…HEAD`.

$ git diff --name-status 63002...HEAD
M       src/notes/for-now-I-am-publishing-mechanism.md

The important thing to remember is that this is just input to the changelog.

3. Process the file modification information to create links to the published pages

The next step will be to create an html page which contains the text of my changelog, nicely formatted, with all file paths transformed to hyperlinks to the corresponding pages.

4. Process the changelog to create an RSS feed

I’m thinking the last part of this step will be to use xast-util-feed to convert changelog/index.html to changelog.rss. It looks like it should be possible to go from HTML to RSS with the steps hast-util-to-xast and then xast-util-feed.

Various thoughts

How do I do updates over time, without overwriting the existing changelog entries?

I could have changelog entries be articles in the changelog/ directory. Then I could use Lume’s Feed plugin to generate the feed.

I could write data files (YAML or JSON) and create a single changelog/index.html from those, growing over time.

Finally, I want the intermediate data representation to be all the atomic units. Because I envision, later, a single list of updates which can be filtered to generated feeds for various parts of the tree: a single series or articles, for example.