deprecate devbranch defaulting to master?

[simeonschaub]

Currently devbranch in deploydocs defaults to master. Since GitHub now uses main as the default name of the dev branch, would it make sense to add a deprecation requiring users to explicitly specify the devbranch, so the default could eventually be changed to main?

[KristofferC]

The vast majority of repos use and likely will use master for a long time so to me it makes sense to keep the current default.

[mortenpi]

New repositories are created with main now, so I don't think it would be unreasonable to have the default in future Documenter releases to be consistent with that. That said, I don't think it makes sense to hard-break immediately, but deprecating the default value and suggesting people to explicitly declare devbranch might make sense.

I think we also want to keep an eye on how PkgTemplates handles it (#233), since I expect most Documenter configurations nowadays to be generated that way. I assume that, at the moment, PkgTemplates still commits the generated content onto master?

Minimally, we should probably add a note to the docs about this.

[christopher-dG]

PkgTemplates lets you manually specify the default branch, and otherwise uses your init.defaultBranch Git setting, which defaults to master. So in the vast majority of cases, people do still get master. The default with no configuration will probably change to main soon: JuliaCI/PkgTemplates.jl#233

I'll make sure to specify devbranch in generated make.jl to make things easier on everyone.

[simeonschaub]

I'll make sure to specify devbranch in generated make.jl to make things easier on everyone.

Currently working on it :)

[christopher-dG]

I think the right change will require the Git changes I mentioned above, which I'll take care of. Once that's in, you can assume that getplugin(t, Git).branch will return the repo's default branch.

edit: I definitely thought this was the PkgTemplates issue 😅 By "mentioned above", I meant JuliaCI/PkgTemplates.jl#233 (comment).

[sylvaticus]

[EDITED]

For those affected, the way to use Documenter to deploy the documentation to GitHub pages is to use the following call to deploydocs in doc/make.jl:

deploydocs(
    repo = "github.com/USERNAME/PACKAGENAME.jl.git",
    devbranch = "main"
)

[abelsiqueira]

Hello all. Are there plans for this change? Will the default be updated to main?

[KristofferC]

Will the default be updated to main?

That would be breaking and require a lot of updates to existing repositories. I personally prefer a bit of extra work for new repositories that use new naming conventions over breaking things that currently work.

[abelsiqueira]

But what's the official position? Will a date or version be set for a deprecation? It won't happen until some trigger? It won't happen at all?
This issue has been open for almost a year, and from the message above, the fix is the same for old repos: add debranch="master" and it's done.

[nickrobinson251]

That would be breaking

we can just put it in a breaking release. i don't see why Documenter.jl would be different to other packages; if you want to avoid getting breaking changes, set a compat entry in the Project.toml.

[oxinabox]

Can we workout something that is automatic?
Like a default of devbranch=MainOrMaster()
which initially tries to use "main" but if that doesn't exist, then it retries using "master" ?

That feels feasible, since we do get an error when trying to use "master" on something that uses "main".
And the chance of having both and not having "master" as a stale old branch is unlikely (and those cases can write "master").

We could even do something more general that also perhaps accepts "trunk" and "dev" ?

[nickrobinson251]

i believe it's now been >1 year since GitHub changed to having the default branch be named main, and also >6 months ago that GitLab also made this change (i believe BitBucket has changed the default too but i dunno when they did it).

Anyway, now it's no longer brand new (and is the default for all(?) major git-hosting-services), i think it's reasonable to reconsider changing the default

of course, something automatic that would be unlikely to break things in practice would be nicest 😊

[KristofferC]

we can just put it in a breaking release

This doesn't change the work that has to be done downstream. Breaking changes are bad and the cost should always be considered. And even if you make a breaking release, it is ideal to keep the amount of breakage as low as possible.

Trying to do something automatic here sounds like a much better plan forward. It should not be very hard for someone that is interested in doing this, see eg https://stackoverflow.com/questions/28666357/git-how-to-get-default-branch