# Automatic merging guidelines

These are the guidelines that a pull request must pass in order to be automatically merged.

All of those guidelines are enabled on the General registry.

For other registries, some of these guidelines can be disabled.

## New packages

1. The package name should start with an upper-case letter, contain only ASCII alphanumeric characters, and contain at least one lowercase letter.
2. The name is at least 5 characters long.
4. Repo URL ends with /PackageName.jl.git.
5. There is an upper-bounded [compat] entry for julia that only includes a finite number of breaking releases of Julia.
6. Dependencies: All dependencies should have [compat] entries that are upper-bounded and only include a finite number of breaking releases. For more information, please see the "Upper bounded [compat] entries" subsection under "Additional information" below.
7. Name is composed of ASCII characters only.
8. Package installation: The package should be installable (Pkg.add("PackageName")).
10. License: The package should have an OSI-approved software license located in the top-level directory of the package code, e.g. in a file named LICENSE or LICENSE.md. This check is required for the General registry. For other registries, registry maintainers have the option to disable this check.
11. Package loading: The package should be loadable (import PackageName).
12. To prevent confusion between similarly named packages, the names of new packages must also satisfy the following three checks: (for more information, please see the "Name similarity distance check" subsection under "Additional information" below)
• the Damerau–Levenshtein distance between the package name and the name of any existing package must be at least 3.
• the Damerau–Levenshtein distance between the lowercased version of a package name and the lowercased version of the name of any existing package must be at least 2.
• and a visual distance from VisualStringDistances.jl between the package name and any existing package must exceeds a certain a hand-chosen threshold (currently 2.5).

## New versions of existing packages

1. Version number: Should be a standard increment and not skip versions. This means incrementing the patch/minor/major version with +1 compared to previous (if any) releases. If, for example, 1.0.0 and 1.1.0 are existing versions, valid new versions are 1.0.1, 1.1.1, 1.2.0 and 2.0.0. Invalid new versions include 1.0.2 (skips 1.0.1), 1.3.0 (skips 1.2.0), 3.0.0 (skips 2.0.0) etc.
2. There is an upper-bounded [compat] entry for julia that only includes a finite number of breaking releases of Julia.
3. Dependencies: All dependencies should have [compat] entries that are upper-bounded and only include a finite number of breaking releases. For more information, please see the "Upper bounded [compat] entries" subsection under "Additional information" below.
4. If it is a patch release, then it does not narrow the [compat] range for julia.
5. Package installation: The package should be installable (Pkg.add("PackageName")).
7. License: The package should have an OSI-approved software license located in the top-level directory of the package code, e.g. in a file named LICENSE or LICENSE.md. This check is required for the General registry. For other registries, registry maintainers have the option to disable this check.
8. Package loading: The package should be loadable (import PackageName).

### Upper-bounded [compat] entries

For example, the following [compat] entries meet the criteria for automatic merging:

[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:

[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:

[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 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 and 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):

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.