StackExchange
Use semantic versioning & improve Docker image tagging
I want to propose the use of semantic versioning for this project. It would allow users to depend on the latest release of any major version without the risk of breaking their integrations. The version numbers would indicate whether a new release is breaking, includes a new feature, or includes a bug fix.
Additionally, I want to propose a slightly different format for the Docker image tags that do not include the "v" prefix and additional tags for major and minor releases. In combination with my first proposal, this would allow users to depend on, e.g. stackexchange/dnscontrol:3 in their CI pipelines a) without the fear of breaking their pipelines by new releases and b) always using the latest features, bug fixes, and security patches.
TBH, I thought I was using semantic versioning and I'm glad you brought this to my attention. I'd appreciate help identifying and fixing the ways we aren't semantic.
Should the semantic versioning refer to the dnsconfig.js file format or the code?
P.S. I've only bumped the major version for radical changes like the change from python to go (1 to 2... before this was open sourced), and when we changed the provider interface (2 to 3).
CC @atma-stackoverflow
Should the semantic versioning refer to the dnsconfig.js file format or the code?
Semantic versioning is only concerned with the public API. It is all about the impact on the user of the software, not its internals.
In this case, breaking changes in the dnscontrol.js file format or usage, the usage of the CLI, or any other public-facing interface requires the release of a major version.
Ah, I see. The 1-to-2 change was an API change but the 2-to-3 change didn't really need to increment the minor number.
I think we've been pretty careful so far. For example, we added --expect-no-changes rather than break old scripts that assumed dnscontrol preview didn't exit with an error if there were changes.
Are there particular breakages you are concerned with?
P.S. My plan for the TXT changes we're discussing are to do them in an upward compatible way. If that can't be achieved, we'll increment the major number.
For example, we added
--expect-no-changesrather than break old scripts that assumed dnscontrol preview didn't exit with an error if there were changes.
That is actually a behaviour that I would like to be an opt-out feature in the next major version. I am currently running all pipelines with this flag.
Are there particular breakages you are concerned with?
The introduction and requirement of AUTOSPLIT was a breaking change that would have broken many setups if automatic updates of the Docker images were possible, for example.
P.S. you can always increment the major version even if there are no public-facing changes if, for example, it helps to organise an overhaul of some characteristic of the providers.
Good point. I've added a issue to track that: https://github.com/StackExchange/dnscontrol/issues/1057
Ah, I thought AUTOSPLIT was backwards compatible. My error.
Ah, I thought
AUTOSPLITwas backwards compatible. My error.
You mentioned it as one in release v3.5.0 ;)
Oh, dang. Yes, release v3.5.0 broke people. My apologies for forgetting that In my defense, it should have only broken providers that were only working by accident of the fact that they take long TXT records and break them up internally. (not an excuse, just an explanation)
Moving right along...
Hopefully #1063 unbroke the breakage of v3.5.0.
Can you try your current master branch and see if your current dnsconfig.js works?
My hope is that in the current master, all AUTOSPLIT commands become a no-op and things "just magically work".
Can you try your current
masterbranch and see if your currentdnsconfig.jsworks?
It works (with Cloudflare).
On the Docker image tags: could we introduce tags like 3, 3.7, and 3.7.0 for the current stable version?
Can you try your current
masterbranch and see if your currentdnsconfig.jsworks?It works (with Cloudflare).
Great!
On the Docker image tags: could we introduce tags like
3,3.7, and3.7.0for the current stable version?
Sure! Can you send a PR? (ngl... I'm no docker expert)
Tom
Can you send a PR?
Sure! I tried to figure out how you are building and uploading your images to Docker Hub, but I could not.
Is it Docker Hub building and publishing the images?
I've been building Docker images for dnscontrol and would appreciate it if others can test it out. It's available on both Docker Hub and GitHub.
Not in front of the computer right now. Will post links later.
[EDIT]
Images are here. https://hub.docker.com/r/jauderho/dnscontrol/tags?page=1&ordering=last_updated
Dockerfile is available at the same location
Hi @jauderho ! Thanks for building docker images.
I'm happy to report that the build system now reliably builds and uploads docker containers. See https://hub.docker.com/r/stackexchange/dnscontrol/
Does this resolve the issues raised in this bug?
Tom,
A few observations:
- I'm of the opinion of picking either a tag starting with a v or not but not both
- It's unclear how much value is added by having architecture specific tags. It might be better just to advertise by version tag and add additional architectures as desired/needed. This would also simplify the goreleaser config
- Depending on how far you want to go, it is now possible to sign and generate SBOMs with goreleaser. Something to think about. I can provide examples if interested
- Given how aggressively Docker Hub rate limits now, I would suggest publishing to GitHub Container Registry too. I've switched most of my Compose files to GHCR and it's been much better from not getting throttled
Good feedback, Thanks!
I'll remove the non-"v" version. That's easy. https://github.com/StackExchange/dnscontrol/pull/2363
The other changes... to be fully transparent, the .goreleaser.yml file was created by someone else and I'm just learning how it works. I don't want to make big changes right before a major release (this week). However I agree with the suggestions and will keep them in mind!
Let's pick up when you get back into the swing of things.
For reference, here is a .goreleaser.yml that you can work off of for SBOM generation and signing. Start at line 128, https://github.com/jauderho/bl3auto/blob/main/.goreleaser.yml#L128
I've also been experimenting with packaging SBOMs with my container images. For an example, see https://github.com/jauderho/dockerfiles/blob/main/.github/workflows/age.yml#L111
We've reworked the CI/CD system and I believe this was fixed. Please confirm.
We've reworked the CI/CD system and I believe this was fixed. Please confirm.
Looks good to me.