Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Default to accepting either master or main as the devbranch #1727

Closed
wants to merge 3 commits into from
Closed

Default to accepting either master or main as the devbranch #1727

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0f2147d
Default to accepting either master or main as the devbranch
oxinabox Nov 10, 2021
e60cdaa
don'
oxinabox Nov 10, 2021
f3a97fe
include docstring for CommonDevBranches
oxinabox Nov 10, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions src/Documenter.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -329,7 +329,7 @@ include("deployconfig.jl")
branch = "gh-pages",
deps = nothing | <Function>,
make = nothing | <Function>,
devbranch = "master",
devbranch = CommonDevBranches(),
devurl = "dev",
versions = ["stable" => "v^", "v#.#", devurl => devurl],
forcepush = false,
Expand Down Expand Up @@ -415,7 +415,9 @@ deps = Deps.pip("pygments", "mkdocs")
executed.

**`devbranch`** is the branch that "tracks" the in-development version of the generated
documentation. By default this value is set to `"master"`.
documentation. By default this value is set to `CommonDevBranches()`, which matches either
`master` or `main`. But to set it explictly you can use a string. Which you should do if you
use either `master` or `main` for some other purpose.

**`devurl`** the folder that in-development version of the docs will be deployed.
Defaults to `"dev"`.
Expand Down Expand Up @@ -491,7 +493,7 @@ function deploydocs(;
deps = nothing,
make = nothing,

devbranch = "master",
devbranch = CommonDevBranches(),
devurl = "dev",
versions = ["stable" => "v^", "v#.#", devurl => devurl],
forcepush::Bool = false,
Expand Down
34 changes: 23 additions & 11 deletions src/deployconfig.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,18 @@ marker(x) = x ? "✔" : "✘"

env_nonempty(key) = !isempty(get(ENV, key, ""))


"""
CommonDevBranches

A stand-in for the name of the devbranch. Rather than hardcoding to `master` or `main` this
accepts any of `master`, `main`.
"""
struct CommonDevBranches end

matches_devbranch(branchname, devbranch) = branchname == devbranch
fredrikekre marked this conversation as resolved.
Show resolved Hide resolved
matches_devbranch(branchname, ::CommonDevBranches) = branchname ∈ ("main", "master", "dev")
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
matches_devbranch(branchname, ::CommonDevBranches) = branchname ∈ ("main", "master", "dev")
matches_devbranch(branchname, ::CommonDevBranches) = branchname ∈ ("main", "master")

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Before I was considering also allowing dev.
But the only repo i know that uses dev is MLJ, and they do not see the devbranch=dev argument.
And so accepting that would potentially break their workflow.
https://github.com/alan-turing-institute/MLJ.jl/blob/96562a60a70aebc3f0d768147ff9dab4549ddfa5/docs/make.jl#L98-L101


#############
# Travis CI #
#############
Expand All @@ -130,7 +142,7 @@ when using the `Travis` configuration:

- `TRAVIS_BRANCH`: unless `TRAVIS_TAG` is non-empty, this must have the same value as
the `devbranch` keyword to [`deploydocs`](@ref). This makes sure that only the
development branch (commonly, the `master` branch) will deploy the "dev" documentation
development branch will deploy the "dev" documentation
(deployed into a directory specified by the `devurl` keyword to [`deploydocs`](@ref)).

- `TRAVIS_TAG`: if set, a tagged version deployment is performed instead; the value
Expand Down Expand Up @@ -205,7 +217,7 @@ function deploy_folder(cfg::Travis;
println(io, "- $(marker(pr_ok)) ENV[\"TRAVIS_PULL_REQUEST\"]=\"$(cfg.travis_pull_request)\" is \"false\"")
all_ok &= pr_ok
## deploydocs' devbranch should match TRAVIS_BRANCH
branch_ok = !isempty(cfg.travis_tag) || cfg.travis_branch == devbranch
branch_ok = !isempty(cfg.travis_tag) || matches_devbranch(cfg.travis_branch, devbranch)
all_ok &= branch_ok
println(io, "- $(marker(branch_ok)) ENV[\"TRAVIS_BRANCH\"] matches devbranch=\"$(devbranch)\"")
deploy_branch = branch
Expand Down Expand Up @@ -241,11 +253,11 @@ function deploy_folder(cfg::Travis;
@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`.
current branch (\$TRAVIS_BRANCH) is "main".

If your primary development branch is 'main', you must explicitly pass `devbranch = "main"`
to deploydocs.
Or remove the `devbranch` setting to fallback to the default which accepts both.

See #1443 for more discussion: https://github.com/JuliaDocs/Documenter.jl/issues/1443
"""
Comment on lines 253 to 263
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we can just delete this whole condition and warning message?
(and the other several copies of it for the other CI providers)

It seems like people are not going to do it by mistake anymore, with the new default?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mortenpi you added this warning in #1489
what do you think of just removing it?

Expand Down Expand Up @@ -348,7 +360,7 @@ function deploy_folder(cfg::GitHubActions;
println(io, "- $(marker(event_ok)) ENV[\"GITHUB_EVENT_NAME\"]=\"$(cfg.github_event_name)\" is \"push\"")
## deploydocs' devbranch should match the current branch
m = match(r"^refs\/heads\/(.*)$", cfg.github_ref)
branch_ok = m === nothing ? false : String(m.captures[1]) == devbranch
branch_ok = m === nothing ? false : matches_devbranch(String(m.captures[1]), devbranch)
all_ok &= branch_ok
println(io, "- $(marker(branch_ok)) ENV[\"GITHUB_REF\"] matches devbranch=\"$(devbranch)\"")
deploy_branch = branch
Expand Down Expand Up @@ -398,11 +410,11 @@ function deploy_folder(cfg::GitHubActions;
@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`.
current branch (from \$GITHUB_REF) is "main".

If your primary development branch is 'main', you must explicitly pass `devbranch = "main"`
to deploydocs.
Or remove the `devbranch` setting to fallback to the default which accepts both.

See #1443 for more discussion: https://github.com/JuliaDocs/Documenter.jl/issues/1443
"""
Expand Down Expand Up @@ -664,7 +676,7 @@ function deploy_folder(
deploy_branch = branch_previews
deploy_repo = repo_previews
else
branch_ok = !isempty(cfg.commit_tag) || cfg.commit_branch == devbranch
branch_ok = !isempty(cfg.commit_tag) || matches_devbranch(cfg.commit_branch, devbranch)
all_ok &= branch_ok
println(
io,
Expand Down Expand Up @@ -804,7 +816,7 @@ function deploy_folder(
deploy_branch = branch_previews
deploy_repo = repo_previews
else
branch_ok = !isempty(cfg.commit_tag) || cfg.commit_branch == devbranch
branch_ok = !isempty(cfg.commit_tag) || matches_devbranch(cfg.commit_branch, devbranch)
all_ok &= branch_ok
println(
io,
Expand All @@ -826,11 +838,11 @@ function deploy_folder(
@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`.
current branch (\$BUILDKITE_BRANCH) is "main".

If your primary development branch is 'main', you must explicitly pass `devbranch = "main"`
to deploydocs.
Or remove the `devbranch` setting to fallback to the default which accepts both.

See #1443 for more discussion: https://github.com/JuliaDocs/Documenter.jl/issues/1443
"""
Expand Down