Sharing a simple idea that I alighted on recently to help me keep track of changes that I do to a module. Sharing it here in case it helps anyone else. In module development, I only use GitHub for tracking issues as I’ve lacked the time and skills to get the benefit of automated building in a way that saves any effort. If you’re able to use the tools more effectively, then likely you won’t need the extra step I describe here.
The idea is to embed a Change Log table into the module using the Vassal Editor’s Folder feature, which has no effect on module functionality. Example below shows the main folder named for a beta/production release and sub-folders for each change numbered for the “alpha” release at which they were entered. The description text is a GitHub issue number and a summary of what I’ve changed. I create another main folder as releases progress, at which point I reset the alpha release number.
I think its a good idea to have some sort of change log with the module, and I appreciate you sharing your idea. Let me give share some thoughts on your solution.
A question: How to you store your module in Git? As a .vmod file? Or as individual images, an XML and Java files, and so on? If you store it as a .vmod, I guess there’s nothing really to build in any kind of CI/CD. If you store the data as individual graphics files and XML files, then I guess you do some building, and I guess you have some (semi-)automated fashion to do so. If that’s the case, it shouldn’t be too difficult to put that into a CI/CD.
Also, you say you use Git to track your issues and development. In that case, you already have a change log in Git’s log. You can generate a change log from those commit logs. There are tons of third-party tools for that (e.g., git-cliff) or you can use GitHub’s feature.
Suppose you do generate a change log - say CHANGES, then you can add that file as a plain text help file in the module. When you update the CHANGES file, you do not need to reattach it, but simply update the entry in the module file as a zip file
zip -u Foo.vmod CHANGES
In that way, you only track changes one place - in Git, and you do not need to sync “by-hand”.
Not entirely true. There will be an additional overhead for the user because VASSAL has to parse more XML elements when opening the module. Granted, that overhead is probably only marginal compared to reading in graphics files. But there is a performance penalty. On the other hand, if you add a plain text help file, then that file is never parsed, and it only adds one additional XML element to for VASSAL to parse.
BTW, if you want, you can probably find a tool that will generate a Markdown or even HTML page of your changes. In that case, when the added plain text help file will be formatted, when viewed, by the Java HTML render.
Hi Christian, thanks for responding. I appreciate your suggestions.
I use IntelliJ for Vassal work, so I started out by using that for managing the module components (images, vsav etc) as well. Using the Vassal module template and guidance, I did get a workflow going to produce the module builds on GitHub. I know other developers get good results but I couldn’t get to a method that seamlessly integrated the step between doing work in the Vassal Editor and producing a build, so at that point the value-add wasn’t there for me.
Issues yes, but development - only insofar as I update and (hopefully) close the issue records. I am no longer doing commits for the reason given above. I do recognise that the information I’m recording would be readily available from Git, if I was using it properly.
I could maintain the detailed log in a text file but at the moment it seems smoother as part of the editor session. One thing is that it aids version control and back-tracking, in the absence of properly being able to use Git.
