How to get Documenter to recognize new release?

Tooling
1

After switching the tooling in my (registered) Julia package from pre-1.0 (REQUIRE, attobot) to post-1.0 (Project.toml, Registrator, TagBot action) I’m having trouble getting Documenter to build the docs for the current release and set the stable link correctly.

Before the switch, docs were built and deployed from a julia-0.6 worker running whatever release of Documenter was compatible with it, and now docs are built and deployed from a julia-1.0 worker with Documenter 0.24.x – I have read and followed all the upgrade instructions for the interim Documenter releases, and the new setup does correctly build the docs for my master branch and links them as “dev”; this part seems to work as intended.

I realize this may be some kind of chicken-and-egg problem. In the first step of the tooling switch, I created my Project.toml and in there set version=0.6.0 (the previous release had been 0.5.0). After pushing my commits to Github, the Travis build got triggered and the new docs were built and linked as “dev”. At that stage I guessed this was expected behavior because, although the Project.toml said version=0.6.0, there had not been a release with that version number/tag yet, so Documenter didn’t really have a reason to build docs for “0.6.0” and treat them as “stable”. Then I set up Registrator and the TagBot action on my repo, got my new version registered (yay!) and eventually TagBot kicked in and made the release (yay!) and tagged it. Now, I thought, my repo should be in a state where Documenter would realize that there’s a 0.6.0 release and treat it as stable. So I went to Travis and manually triggered a build from master. The build stage for Documenter runs through, I can see it’s getting the right commit, and it can see the new tag

* [new tag]         v0.6.0       -> v0.6.0

but eventually

Warning: removing `stable` and linking `stable` to `v0.5.0`.

so the 0.6.0 release somehow seems to get ignored. The “dev” branch does have the correct docs for master, but no “0.6.0” docs branch is created, and “stable” still points to the previous 0.5.0 release.

How can I tell Documenter to recognize the new release? IIRC in the past new releases were handled automatically by Documenter, and I guess this should still be happening, so I assume I’ve broken something somewhere… maybe it’s related to the versions.js file? Though I thought that is created automatically.

Note, currently my 0.6.0 and master point to the same commit, would that cause a problem?

2 Likes
2

Most likely you are not running CI on tags. You need something like Literate.jl/.travis.yml at 14afee9ff32c16aa5614d3f4c86b44076c0bed0f · fredrikekre/Literate.jl · GitHub in .travix.yaml or Literate.jl/docs.yml at 14afee9ff32c16aa5614d3f4c86b44076c0bed0f · fredrikekre/Literate.jl · GitHub in gh-actions.yaml.

4 Likes
3

Thanks Fredrik.

I’ve added

branches:
  only:
    - master
    - /^v\d+\.\d+(\.\d+)?(-\S*)?$/

to my .travis.yml and let Travis do its thing. This did not result in the 0.6.0 documentation getting created or the “stable” branch getting updated, perhaps unsurprisingly. As the new commit was done on the master branch, I guess the Travis/Documenter machinery still treated this as “CI on master” instead of “CI on a tag”.

To be honest, I don’t understand how the workflow should be changed in order to automatically get a “CI on a new tag” (release). Isn’t the recommended workflow nowadays:

  1. update the package and documentation
  2. push to Github
  3. this triggers CI
  4. if CI ok, leave a comment for JuliaRegistrator on the commit
  5. the new version gets registered (in METADATA or whatever it’s called now)
  6. TagBot tags the commit and makes a release (vX.Y.Z)

Does the TagBot action now (if “CI on tags” is enabled as per above) trigger another CI run on Travis? If it does, would I need to make a new release for this automatism to kick in? If it doesn’t, how could I trigger the “CI on new tag”? Thanks.

1 Like
4

No, since on master you build the master/dev docs. You will have to build the 0.6 docs manually, since building with CI on the tag is not possible now after the fact.

2 Likes
5

Also struggling with this, traktofon, I was having a look at some repositories (e.g. of fredrikekre aswell as yours) and not certain how to translate it for our repository. I wonder if there is some more lengthy documentation on this somewhere? Curious to understand exactly what all of the options are specifying.

edit: ah I am reading through this more carefully now, perhaps that is what I needed https://github.com/JuliaRegistries/TagBot#personal-access-tokens

6

I do not recommend using personal access tokens.

If you want to make sure that you trigger CI on tags/releases, I recommend that you set up TagBot to use SSH deploy keys: https://github.com/JuliaRegistries/TagBot/blob/master/README.md#ssh-deploy-keys

SSH deploy keys are more secure than personal access tokens.

2 Likes