javadoc-cleanup VS semver

javadoc-cleanup - Create mobile-friendly and SEO ready documentation sites by post-processing javadocs in GitHub Actions

A better approach that speeds up runs of your action is to use a base image that includes all of the tools that your action requires. This way, your Dockerfile only requires the steps necessary to copy the source of your action into the container and to set an entrypoint. Here is an example of the Dockerfile of one of my GitHub Actions (note this one doesn't use the containers that are the subject of this post):

I maintain several GitHub Actions, such as jacoco-badge-generator, generate-sitemap, javadoc-cleanup, and user-statistician. I've also written posts here on DEV about each of these if you'd like more information. GitHub's documentation for GitHub Action developers recommends maintaining a major release tag for the Action so that users can either reference the Action by its specific release tag, such as v1.2.3, or simply by the major release with v1. In fact, it is so commonplace that users will likely assume that your Action supports specifying full version tag or major tag only. Note that some Actions use major release branches (e.g., branch named v1) instead of tags. My intention in this post is not to discuss the advantages/disadvantages of each of these alternative approaches. In the Actions that I maintain, I use major release tags for the simple reason that it is what GitHub's documentation recommends.

We now need a way to detect if the results of the above integration tests are correct. The various actions that I maintain produce files (e.g., jacoco-badge-generator produces coverage badges, and generate-sitemap produces an XML sitemap) or edits existing files (e.g., javadoc-cleanup inserts canonical links and a few other things into the head of javadoc pages). In cases like these, I use Python's unittest module to validate the results. In this case, I define unit test cases in tests/integration.py that verify that the files produced by the action are correct. If any of those tests fail, then Python will exit with a non-zero exit code which will cause the workflow to fail.

The next step uses a GitHub Action that I've implemented javadoc-cleanup to insert canonical URLs into the head of each javadoc page. I also use it to insert a referrer policy of strict-origin-when-cross-origin into the head of each javadoc page, as well as links to my project's favicon, and my web monetization pointer. This step is conditional, like the previous step, and only runs on release and workflow_dispatch events.

This post introduces javadoc-cleanup, a GitHub Action that I developed a while ago for post-processing javadoc documentation prior to deploying to a documentation website. I use it in several of my own Java projects to improve the output of javadoc in a few ways. The functionality of javadoc-cleanup includes the following:

There are two primary ways of implementing a GitHub Action: JavaScript Actions and Container Actions. The latter of which enables implementing Actions in any language via a Docker container. My language of choice for implementing GitHub Actions is Python. The purpose of most of these actions is to produce files (e.g., jacoco-badge-generator produces test coverage badges as SVGs, and generate-sitemap produces an XML sitemap) or to edit files in some way (e.g., javadoc-cleanup can insert canonical links and other user-defined elements into the head of javadoc pages). However, all of these also produce workflow step outputs. For example, generate-sitemap has outputs for the number of pages in the sitemap, and the number of pages excluded from the sitemap due to noindex or robots.txt exclusions; and jacoco-badge-generator has workflow step outputs for the coverage and branches coverage percentages if a user had some reason to use those in later steps of their workflow.

We increase the version of our product as specified in SemVer and deploy it to production, preferably following good deployment practices to have no downtime.

Using Conventional Commits ⭐ as a standard for your commit messages, makes Semantic Versioning 🔖 as easy as can be, with tools like Conventional Changelog 📄 Standard Version 🔖 and Semantic Release 📦🚀

Semantic Versioning: for every update (major, minor, or patch) made, increment the version number according to semantic versioning.

npm automates the process of installing, updating, and managing dependencies, which helps to avoid "dependency hell." It supports semantic versioning (semver) that automatically handles patch and minor updates without breaking the existing code, thus maintaining stability across projects. npm also provides the capability to run scripts and commands defined in package.json, which can automate common tasks such as testing, building, and deployment.

We are pleased to introduce Semantic Versioning and release channels to Snyk CLI from v.1.1291.0 onwards. In this blog post, we will share why we are introducing these changes, what problems these changes solve for our customers, and how our customers can opt-in according to their needs.

Following the Semantic Versioning rules, you should raise the version number every time you need to publish your library. In your "package.json" file, you need to change the version number to reflect whether the changes are major, minor, or patch updates.

Semantic Versioning: An established convention for version numbers following the pattern MAJOR.MINOR.PATCH

Increases the major of the latest tag and prints it As per the Semver spec, it'll also clear the pre-release…

The reason for this is that software libraries and package managers, in general, but specifically here, rely on semantic versioning. Semantic versioning is really useful for distributing packages in a predictable way. What does this look like for our project?

For a more detailed and comprehensive guide on semantic versioning, visit https://semver.org