Print a warning when main/master confusion detected (#1489)

CHANGELOG.md

@@ -14,6 +14,8 @@
 
 * ![Enhancement][badge-enhancement] HTML output now bails early if there are no pages, instead of throwing an `UndefRefError`. In addition, it will also warn if `index.md` is missing and it is not able to generate the main landing page (`index.html`). ([#1201][github-1201], [#1491][github-1491])
 
+* ![Enhancement][badge-enhancement] `deploydocs` now prints a warning on GitHub Actions, Travis CI and Buildkite if the current branch is `main`, but `devbranch = "master`, which indicates a possible Documenter misconfiguration due to GitHub changing the default primary branch of a repository to `main`. ([#1489][github-1489])
+
 ## Version `v0.25.5`
 
 * ![Bugfix][badge-bugfix] In the HTML output, display equations that are wider than the page now get a scrollbar instead of overflowing. ([#1470][github-1470], [#1476][github-1476])
@@ -712,6 +714,7 @@
 [github-1472]: https://github.com/JuliaDocs/Documenter.jl/pull/1472
 [github-1474]: https://github.com/JuliaDocs/Documenter.jl/pull/1474
 [github-1476]: https://github.com/JuliaDocs/Documenter.jl/pull/1476
+[github-1489]: https://github.com/JuliaDocs/Documenter.jl/pull/1489
 [github-1491]: https://github.com/JuliaDocs/Documenter.jl/pull/1491
 [github-1493]: https://github.com/JuliaDocs/Documenter.jl/pull/1493
 

src/deployconfig.jl

@@ -236,6 +236,19 @@ function deploy_folder(cfg::Travis;
     println(io, "- $(marker(type_ok)) ENV[\"TRAVIS_EVENT_TYPE\"]=\"$(cfg.travis_event_type)\" is not \"cron\"")
     print(io, "Deploying: $(marker(all_ok))")
     @info String(take!(io))
+    if build_type === :devbranch && !branch_ok && devbranch == "master" && cfg.travis_branch == "main"
+        @warn """
+        Possible deploydocs() misconfiguration: main vs master
+        Documenter's configured primary development branch (`devbranch`) is "master", but the
+        current branch (\$TRAVIS_BRANCH) is "main". This can happen because Documenter uses
+        GitHub's old default primary branch name as the default value for `devbranch`.
+
+        If your primary development branch is 'main', you must explicitly pass `devbranch = "main"`
+        to deploydocs.
+
+        See #1443 for more discussion: https://github.com/JuliaDocs/Documenter.jl/issues/1443
+        """
+    end
     if all_ok
         return DeployDecision(; all_ok = true,
                                 branch = deploy_branch,
@@ -375,6 +388,19 @@ function deploy_folder(cfg::GitHubActions;
     end
     print(io, "Deploying: $(marker(all_ok))")
     @info String(take!(io))
+    if build_type === :devbranch && !branch_ok && devbranch == "master" && cfg.github_ref == "refs/heads/main"
+        @warn """
+        Possible deploydocs() misconfiguration: main vs master
+        Documenter's configured primary development branch (`devbranch`) is "master", but the
+        current branch (from \$GITHUB_REF) is "main". This can happen because Documenter uses
+        GitHub's old default primary branch name as the default value for `devbranch`.
+
+        If your primary development branch is 'main', you must explicitly pass `devbranch = "main"`
+        to deploydocs.
+
+        See #1443 for more discussion: https://github.com/JuliaDocs/Documenter.jl/issues/1443
+        """
+    end
     if all_ok
         return DeployDecision(; all_ok = true,
                                 branch = deploy_branch,
@@ -762,6 +788,19 @@ function deploy_folder(
 
     print(io, "Deploying to folder $(repr(subfolder)): $(marker(all_ok))")
     @info String(take!(io))
+    if build_type === :devbranch && !branch_ok && devbranch == "master" && cfg.commit_branch == "main"
+        @warn """
+        Possible deploydocs() misconfiguration: main vs master
+        Documenter's configured primary development branch (`devbranch`) is "master", but the
+        current branch (\$BUILDKITE_BRANCH) is "main". This can happen because Documenter uses
+        GitHub's old default primary branch name as the default value for `devbranch`.
+
+        If your primary development branch is 'main', you must explicitly pass `devbranch = "main"`
+        to deploydocs.
+
+        See #1443 for more discussion: https://github.com/JuliaDocs/Documenter.jl/issues/1443
+        """
+    end
 
     if all_ok
         return DeployDecision(;