Merge #405

405: Auto-generate the documentation page with the list of AutoMerge guidelines r=DilumAluthge,ericphanson,GunnarFarneback a=DilumAluthge

Currently, we duplicate a lot of this information. For example, the guidelines themselves are defined in the source code of the `RegistryCI.jl` package (specifically in the `RegistryCI.AutoMerge` submodule), but the documentation of the guidelines is in the [General registry README](https://github.com/JuliaRegistries/General/blob/master/README.md).

With this PR, I attempt to implement the [don't repeat yourself (DRY)](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) principle by centralizing the definition of the guidelines and their documentation into a single place, specifically the AutoMerge source code, which is now the single source of truth.

Then, we use the AutoMerge source code to auto-generate a documentation page that has the list of AutoMerge guidelines.

Once this PR is merged and a new version of RegistryCI has been tagged, we can remove the list of AutoMerge guidelines from the [General registry README](https://github.com/JuliaRegistries/General/blob/master/README.md) and replace it with a link to the appropriate RegistryCI.jl documentation page.

Co-authored-by: Dilum Aluthge <[email protected]>

Project.toml

@@ -1,7 +1,7 @@
 name = "RegistryCI"
 uuid = "0c95cc5f-2f7e-43fe-82dd-79dbcba86b32"
 authors = ["Dilum Aluthge <[email protected]>", "Fredrik Ekre <[email protected]>", "contributors"]
-version = "7.0.2"
+version = "7.1.0"
 
 [deps]
 Base64 = "2a0f44e3-6c83-55bd-87e4-b1978d98bd5f"

docs/make.jl

@@ -26,4 +26,5 @@ makedocs(;
 
 deploydocs(;
     repo="github.com/JuliaRegistries/RegistryCI.jl",
+    push_preview=false,
 )

docs/src/guidelines.md

@@ -4,5 +4,115 @@ CurrentModule = RegistryCI
 
 # Automatic merging guidelines
 
-For the list of automatic merging (AutoMerge) guidelines, please see the
-[General registry README](https://github.com/JuliaRegistries/General/blob/master/README.md#automatic-merging-of-pull-requests).
+## New packages
+
+```@eval
+import RegistryCI
+import Markdown
+
+function guidelines_to_markdown_output(guidelines_function::Function)
+    guidelines = guidelines_function(;
+        check_license = true,
+        this_is_jll_package = false,
+        this_pr_can_use_special_jll_exceptions = false,
+    )
+    filter!(x -> x[1] != :update_status, guidelines)
+    filter!(x -> !(x[1].docs isa Nothing), guidelines)
+    docs = [rstrip(x[1].docs) for x in guidelines]
+    output_string = join(string.(collect(1:length(docs)), Ref(". "), docs), "\n")
+    output_markdown = Markdown.parse(output_string)
+    return output_markdown
+end
+
+const guidelines_function = RegistryCI.AutoMerge.get_automerge_guidelines_new_packages
+const output_markdown = guidelines_to_markdown_output(guidelines_function)
+
+return output_markdown
+```
+
+## New versions of existing packages
+
+```@eval
+import RegistryCI
+import Markdown
+
+function guidelines_to_markdown_output(guidelines_function::Function)
+    guidelines = guidelines_function(;
+        check_license = true,
+        this_is_jll_package = false,
+        this_pr_can_use_special_jll_exceptions = false,
+    )
+    filter!(x -> x[1] != :update_status, guidelines)
+    filter!(x -> !(x[1].docs isa Nothing), guidelines)
+    docs = [rstrip(x[1].docs) for x in guidelines]
+    output_string = join(string.(collect(1:length(docs)), Ref(". "), docs), "\n")
+    output_markdown = Markdown.parse(output_string)
+    return output_markdown
+end
+
+const guidelines_function = RegistryCI.AutoMerge.get_automerge_guidelines_new_versions
+const output_markdown = guidelines_to_markdown_output(guidelines_function)
+
+return output_markdown
+```
+
+## Additional information
+
+### Upper-bounded `[compat]` entries
+
+For example, the following `[compat]` entries meet the criteria for automatic merging:
+```toml
+[compat]
+PackageA = "1"          # [1.0.0, 2.0.0), has upper bound (good)
+PackageB = "0.1, 0.2"   # [0.1.0, 0.3.0), has upper bound (good)
+```
+The following `[compat]` entries do NOT meet the criteria for automatic merging:
+```toml
+[compat]
+PackageC = ">=3"        # [3.0.0, ∞), no upper bound (bad)
+PackageD = ">=0.4, <1"  # [0, ∞), no lower bound, no upper bound (very bad)
+```
+Please note: each `[compat]` entry must include only a finite number of breaking releases. Therefore, the following `[compat]` entries do NOT meet the criteria for automatic merging:
+```toml
+[compat]
+PackageE = "0"          # includes infinitely many breaking 0.x releases of PackageE (bad)
+PackageF = "0.2 - 0"    # includes infinitely many breaking 0.x releases of PackageF (bad)
+PackageG = "0.2 - 1"    # includes infinitely many breaking 0.x releases of PackageG (bad)
+```
+See [Pkg's documentation](https://julialang.github.io/Pkg.jl/v1/compatibility/) for specification of `[compat]` entries in your
+`Project.toml` file.
+
+(**Note:** Standard libraries are excluded for this criterion since they are bundled
+with Julia, and, hence, implicitly included in the `[compat]` entry for Julia.
+For the time being, JLL dependencies are also excluded for this criterion because they
+often have non-standard version numbering schemes; however, this may change in the future.)
+
+You may find [CompatHelper.jl](https://github.com/bcbi/CompatHelper.jl) and [PackageCompatUI.jl](https://github.com/GunnarFarneback/PackageCompatUI.jl) helpful for maintaining up-to-date `[compat]` entries.
+
+### Name similarity distance check
+
+These checks and tolerances are subject to change in order to improve the
+process.
+
+To test yourself that a tentative package name, say `MyPackage` meets these
+checks, you can use the following code (after adding the RegistryCI package
+to your Julia environment):
+
+```julia
+using RegistryCI
+using RegistryCI.AutoMerge
+all_pkg_names = AutoMerge.get_all_non_jll_package_names(path_to_registry)
+AutoMerge.meets_distance_check("MyPackage", all_pkg_names)
+```
+
+where `path_to_registry` is a path to the folder containing the registry of
+interest. For the General Julia registry, usually `path_to_registry =
+joinpath(DEPOT_PATH[1], "registries", "General")` if you haven't changed
+your `DEPOT_PATH`. This will return a boolean, indicating whether or not
+your tentative package name passed the check, as well as a string,
+indicating what the problem is in the event the check did not pass.
+
+Note that these automerge guidelines are deliberately conservative: it is
+very possible for a perfectly good name to not pass the automatic checks and
+require manual merging. They simply exist to provide a fast path so that
+manual review is not required for every new package.

src/AutoMerge/AutoMerge.jl

@@ -17,26 +17,25 @@ import RegistryTools
 import ..RegistryCI
 import Tar
 
-include("assert.jl")
-
 include("types.jl")
-
 include("ciservice.jl")
-include("public.jl")
 
 include("api_rate_limiting.jl")
+include("assert.jl")
 include("automerge_comment.jl")
 include("changed_files.jl")
 include("cron.jl")
+include("dependency_confusion.jl")
 include("github.jl")
 include("guidelines.jl")
 include("jll.jl")
 include("new-package.jl")
 include("new-version.jl")
 include("not-automerge-applicable.jl")
+include("public.jl")
 include("pull-requests.jl")
 include("semver.jl")
+include("update_status.jl")
 include("util.jl")
-include("dependency_confusion.jl")
 
 end # module

src/AutoMerge/assert.jl

@@ -1,6 +1,3 @@
-struct AlwaysAssertionError <: Exception
-    msg::String
-end
 AlwaysAssertionError() = AlwaysAssertionError("")
 
 # The documentation for the `Base.@assert` macro says: "Warning: An assert might be

src/AutoMerge/changed_files.jl

@@ -16,14 +16,17 @@ function allowed_changed_files(::NewVersion, pkg::String)
     return result
 end
 
-const guideline_pr_only_changes_allowed_files =
-    Guideline("Only modifies the files that it's allowed to modify",
-              data -> pr_only_changes_allowed_files(data.api,
-                                                    data.registration_type,
-                                                    data.registry,
-                                                    data.pr,
-                                                    data.pkg;
-                                                    auth = data.auth))
+const guideline_pr_only_changes_allowed_files = Guideline(;
+    info = "Only modifies the files that it's allowed to modify.",
+    docs = nothing,
+    check = data -> pr_only_changes_allowed_files(data.api,
+        data.registration_type,
+        data.registry,
+        data.pr,
+        data.pkg;
+        auth = data.auth,
+    ),
+)
 
 function pr_only_changes_allowed_files(api::GitHub.GitHubAPI,
                                        t::Union{NewPackage, NewVersion},

src/AutoMerge/dependency_confusion.jl

@@ -1,11 +1,15 @@
 # TODO: Add a more thorough explanation of the dependency confusion
 # vulnerability and how this guideline mitigates it.
 
-const guideline_dependency_confusion =
-    Guideline("No UUID conflict with other registries.",
-              data -> has_no_dependency_confusion(data.pkg,
-                                                  data.registry_head,
-                                                  data.public_registries))
+const guideline_dependency_confusion = Guideline(;
+    info = "No UUID conflict with other registries.",
+    docs = nothing,
+    check = data -> has_no_dependency_confusion(
+        data.pkg,
+        data.registry_head,
+        data.public_registries,
+    ),
+)
 
 # TODO: Needs a strategy to handle connection failures for the public
 # registries. Preferably they should also be cloned only once and then