Compat admonitions and NEWS for Julia 1.1 (#30230)

Addition of NEWS and compat admonitions for important changes between Julia 1.0 and 1.1, including:

- Custom .css-style for compat admonitions.

- Information about compat annotations to CONTRIBUTING.md.

- NEWS.md entry for PRs #30090, #30035, #30022, #29978,
  #29969, #29858, #29845, #29754, #29638, #29636, #29615,
  #29600, #29506, #29469, #29316, #29259, #29178, #29153,
  #29033, #28902, #28761, #28745, #28708, #28696, #29997,
  #28790, #29092, #29108, #29782

- Compat annotation for PRs #30090, #30013, #29978,
  #29890, #29858, #29827, #29754, #29679, #29636, #29623,
  #29600, #29440, #29316, #29259, #29178, #29157, #29153,
  #29033, #28902, #28878, #28761, #28708, #28156, #29733,
  #29670, #29997, #28790, #29092, #29108, #29782, #25278

- Documentation for broadcasting CartesianIndices (#30230).
- Documentation for Base.julia_cmd().
- Documentation for colon constructor of CartesianIndices (#29440).
- Documentation for ^(::Matrix, ::Number) and ^(::Number, ::Matrix).

- Run NEWS-update.jl.


Co-authored-by: Morten Piibeleht <morten.piibeleht@gmail.com>
Co-authored-by: Fredrik Ekre <ekrefredrik@gmail.com>

CONTRIBUTING.md

@@ -184,6 +184,21 @@ A doctest needs to match an interactive REPL including the `julia>` prompt. To r
 
 For new functionality and other substantial changes, add a brief summary to `NEWS.md`. The news item should cross reference the pull request (PR) parenthetically, in the form `([#pr])`; after adding this, run `./julia doc/NEWS-update.jl` from the `julia` directory to update the cross-reference links. To add the PR reference number, first create the PR, then push an additional commit updating `NEWS.md` with the PR reference number.
 
+#### Annotations for new features, deprecations and behavior changes
+
+API additions and deprecations, and minor behavior changes are allowed in minor version releases.
+For documented features that are part of the public API, a compatibility note should be added into
+the manual or the docstring. It should state the Julia minor version that made changed the behavior
+and have a brief message describing the change.
+
+At the moment, this should always be done with the following `compat` admonition
+(so that it would be possible to programmatically find the annotations in the future):
+
+  ```
+  !!! compat "Julia 1.X"
+      This method was added in Julia 1.X.
+  ```
+
 ### Contributing to core functionality or base libraries
 
 *By contributing code to Julia, you are agreeing to release it under the [MIT License](https://github.com/JuliaLang/julia/tree/master/LICENSE.md).*

NEWS.md

@@ -39,6 +39,8 @@ New library functions
   * `isnothing(::Any)` function, to check whether something is a `Nothing`, returns a `Bool` ([#29679]).
   * `getpid(::Process)` method ([#24064]).
   * `eachrow`, `eachcol` and `eachslice` functions provide efficient iterators over slices of arrays ([#29749]).
+  * `fieldtypes(T::Type)` which return the declared types of the field in type T ([#29600]).
+  * `uuid5` has been added to the `UUIDs` standard library ([#28761]).
 
 Standard library changes
 ------------------------
@@ -50,7 +52,7 @@ Standard library changes
   * `range` can accept the stop value as a positional argument, e.g. `range(1,10,step=2)` ([#28708]).
   * `edit` can now be called on a module to edit the file that defines it ([#29636]).
   * `diff` now supports arrays of arbitrary dimensionality and can operate over any dimension ([#29827]).
-  * `sprandn` now supports result types like `ComplexF64` or `Float32` ([#30083]).
+  * `sprandn` now supports specifying the output element type ([#30083]).
   * All compiler-reflection tools (i.e. the `code_` class of functions and macros) now print accurate
     line number and inlining information in a common style, and take an optional parameter (debuginfo=:default)
     to control the verbosity of the metadata shown ([#29893]).
@@ -66,11 +68,42 @@ Standard library changes
   * `Base.tail` now works on named tuples ([#29595]).
   * `randperm` and `randcycle` now use the type of their argument to determine the element type of
     the returned array ([#29670]).
+  * The process id is appended to malloc log files in order to track memory allocations of
+    multiple processes ([#29969]).
+  * `Base.julia_cmd` now propagates the `--inline=(yes|no)` flag ([#29858]).
+  * New `DateTime(::Date, ::Time)` constructor ([#29754]).
+  * `isdiag` and `isposdef` for `Diagonal` and `UniformScaling` ([#29638]).
+  * `mul!`, `rmul!` and `lmul!` methods for `UniformScaling` ([#29506]).
+  * `Symmetric` and `Hermitian` matrices now preserve the wrapper when scaled with a number ([#29469]).
+  * New `edit(m::Module)` method which opens the main source file for module `m` ([#29636]).
+  * `Base.@kwdef` can now be used for parametric structs, and for structs with supertypes ([#29316]).
+  * `merge(::NamedTuple, ::NamedTuple...)` can now be used with more than 2 `NamedTuple`s ([#29259]).
+  * `Future.copy!` has been moved to `Base` ([#29178]).
+  * New `ncodeunits(c::Char)` method as a fast equivalent to `ncodeunits(string(c))` ([#29153]).
+  * `mean` and `var` now handles the empty case ([#29033]).
+  * New `sort!(::AbstractArray; dims)` method that can sort the array along the `dims` dimension ([#28902]).
+  * `range` now accept `stop` as a positional argument ([#28708]).
+  * `parse(Bool, str)` is now supported ([#29997]).
+  * `copyto!(::AbstractMatrix, ::UniformScaling)` supports rectangular matrices now ([#28790]).
+  * In `put!(c::Channel{T}, v)`, `v` now gets converted to `T` as `put!` is being called ([#29092]).
+  * `current_project()` now searches the parent directories of a Git repository for a `Project.toml` file.
+    This also affects the behavior of the `--project` command line option when using the default
+    `--project=@.` ([#29108]).
+  * Exponentiation operator `^` now supports raising a `Irrational` to an `AbstractMatrix` power ([#29782]).
   * A new method `rand(::Tuple)` implements sampling from the values of a tuple ([#25278]).
 
 Compiler/Runtime improvements
 -----------------------------
 
+External dependencies
+---------------------
+
+  * 7zip (bundled with Julia on Windows) has been upgraded from version 16.04 to 18.05 ([#30035]).
+  * Busybox is no longer bundled with Julia on Windows ([#30022]).
+  * OpenBLAS has been upgraded from 0.3.2 to 0.3.3 ([#29845]).
+  * The source code for Pkg is no longer included in JuliaLang/julia. Pkg is instead
+    downloaded during the build process ([#29615]).
+  * LLVM has been upgraded to 6.0.1 and support for LLVM < 6.0 has been dropped ([#28745], [#28696]).
 
 Deprecated or removed
 ---------------------
@@ -80,9 +113,65 @@ Deprecated or removed
     to get an appropriate task-local buffer and pass it to `grisu()` instead ([#29907]).
   * The internal function `Base._default_type(T)` has been removed. Calls to it should be
     replaced with just the argument `T` ([#29739]).
+  * `peakflops` has been scheduled to move from `InteractiveUtils` to `LinearAlgebra`
+    but is already now available as `LinearAlgebra.peakflops` ([#29978]).
 
 <!--- generated by NEWS-update.jl: -->
+[#21233]: https://github.com/JuliaLang/julia/issues/21233
+[#24064]: https://github.com/JuliaLang/julia/issues/24064
+[#25278]: https://github.com/JuliaLang/julia/issues/25278
 [#28156]: https://github.com/JuliaLang/julia/issues/28156
+[#28506]: https://github.com/JuliaLang/julia/issues/28506
+[#28696]: https://github.com/JuliaLang/julia/issues/28696
+[#28708]: https://github.com/JuliaLang/julia/issues/28708
+[#28745]: https://github.com/JuliaLang/julia/issues/28745
+[#28761]: https://github.com/JuliaLang/julia/issues/28761
+[#28790]: https://github.com/JuliaLang/julia/issues/28790
 [#28878]: https://github.com/JuliaLang/julia/issues/28878
+[#28902]: https://github.com/JuliaLang/julia/issues/28902
+[#29033]: https://github.com/JuliaLang/julia/issues/29033
+[#29092]: https://github.com/JuliaLang/julia/issues/29092
+[#29108]: https://github.com/JuliaLang/julia/issues/29108
+[#29127]: https://github.com/JuliaLang/julia/issues/29127
+[#29153]: https://github.com/JuliaLang/julia/issues/29153
+[#29157]: https://github.com/JuliaLang/julia/issues/29157
+[#29173]: https://github.com/JuliaLang/julia/issues/29173
+[#29178]: https://github.com/JuliaLang/julia/issues/29178
+[#29211]: https://github.com/JuliaLang/julia/issues/29211
+[#29259]: https://github.com/JuliaLang/julia/issues/29259
+[#29316]: https://github.com/JuliaLang/julia/issues/29316
+[#29429]: https://github.com/JuliaLang/julia/issues/29429
 [#29440]: https://github.com/JuliaLang/julia/issues/29440
 [#29442]: https://github.com/JuliaLang/julia/issues/29442
+[#29469]: https://github.com/JuliaLang/julia/issues/29469
+[#29506]: https://github.com/JuliaLang/julia/issues/29506
+[#29595]: https://github.com/JuliaLang/julia/issues/29595
+[#29600]: https://github.com/JuliaLang/julia/issues/29600
+[#29615]: https://github.com/JuliaLang/julia/issues/29615
+[#29636]: https://github.com/JuliaLang/julia/issues/29636
+[#29638]: https://github.com/JuliaLang/julia/issues/29638
+[#29670]: https://github.com/JuliaLang/julia/issues/29670
+[#29679]: https://github.com/JuliaLang/julia/issues/29679
+[#29733]: https://github.com/JuliaLang/julia/issues/29733
+[#29739]: https://github.com/JuliaLang/julia/issues/29739
+[#29749]: https://github.com/JuliaLang/julia/issues/29749
+[#29754]: https://github.com/JuliaLang/julia/issues/29754
+[#29781]: https://github.com/JuliaLang/julia/issues/29781
+[#29782]: https://github.com/JuliaLang/julia/issues/29782
+[#29819]: https://github.com/JuliaLang/julia/issues/29819
+[#29827]: https://github.com/JuliaLang/julia/issues/29827
+[#29845]: https://github.com/JuliaLang/julia/issues/29845
+[#29858]: https://github.com/JuliaLang/julia/issues/29858
+[#29890]: https://github.com/JuliaLang/julia/issues/29890
+[#29893]: https://github.com/JuliaLang/julia/issues/29893
+[#29907]: https://github.com/JuliaLang/julia/issues/29907
+[#29913]: https://github.com/JuliaLang/julia/issues/29913
+[#29968]: https://github.com/JuliaLang/julia/issues/29968
+[#29969]: https://github.com/JuliaLang/julia/issues/29969
+[#29978]: https://github.com/JuliaLang/julia/issues/29978
+[#29980]: https://github.com/JuliaLang/julia/issues/29980
+[#29997]: https://github.com/JuliaLang/julia/issues/29997
+[#30022]: https://github.com/JuliaLang/julia/issues/30022
+[#30035]: https://github.com/JuliaLang/julia/issues/30035
+[#30083]: https://github.com/JuliaLang/julia/issues/30083
+[#30159]: https://github.com/JuliaLang/julia/issues/30159

base/abstractarray.jl

@@ -647,6 +647,10 @@ If `dst` and `src` are of the same type, `dst == src` should hold after
 the call. If `dst` and `src` are multidimensional arrays, they must have
 equal [`axes`](@ref).
 See also [`copyto!`](@ref).
+
+!!! compat "Julia 1.1"
+    This method requires at least Julia 1.1. In Julia 1.0 this method
+    is available from the `Future` standard library as `Future.copy!`.
 """
 copy!(dst::AbstractVector, src::AbstractVector) = append!(empty!(dst), src)
 

base/channels.jl

@@ -245,6 +245,9 @@ Append an item `v` to the channel `c`. Blocks if the channel is full.
 
 For unbuffered channels, blocks until a [`take!`](@ref) is performed by a different
 task.
+
+!!! compat "Julia 1.1"
+    `v` now gets converted to the channel's type with [`convert`](@ref) as `put!` is called.
 """
 function put!(c::Channel{T}, v) where T
     check_channel_state(c)

base/char.jl

@@ -56,6 +56,10 @@ Char
 Return the number of code units required to encode a character as UTF-8.
 This is the number of bytes which will be printed if the character is written
 to an output stream, or `ncodeunits(string(c))` but computed efficiently.
+
+!!! compat "Julia 1.1"
+    This method requires at least Julia 1.1. In Julia 1.0 consider
+    using `ncodeunits(string(c))`.
 """
 ncodeunits(c::Char) = write(devnull, c) # this is surprisingly efficient
 

base/error.jl

@@ -103,6 +103,9 @@ false.
 Explicitly passing `task` will return the current exception stack on an
 arbitrary task. This is useful for inspecting tasks which have failed due to
 uncaught exceptions.
+
+!!! compat "Julia 1.1"
+    This function requires at least Julia 1.1.
 """
 function catch_stack(task=current_task(); include_bt=true)
     raw = ccall(:jl_get_excstack, Any, (Any,Cint,Cint), task, include_bt, typemax(Cint))

base/locks.jl

@@ -246,6 +246,9 @@ Create a level-triggered event source. Tasks that call [`wait`](@ref) on an
 `Event` are suspended and queued until `notify` is called on the `Event`.
 After `notify` is called, the `Event` remains in a signaled state and
 tasks will no longer block when waiting for it.
+
+!!! compat "Julia 1.1"
+    This functionality requires at least Julia 1.1.
 """
 mutable struct Event
     lock::Mutex

base/mpfr.jl

@@ -151,6 +151,11 @@ global precision; `convert` will always return `x`.
 convenience since decimal literals are converted to `Float64` when parsed, so
 `BigFloat(2.1)` may not yield what you expect.
 
+!!! compat "Julia 1.1"
+    `precision` as a keyword argument requires at least Julia 1.1.
+    In Julia 1.0 `precision` is the second positional argument (`BigFloat(x, precision)`).
+
+# Examples
 ```jldoctest
 julia> BigFloat(2.1) # 2.1 here is a Float64
 2.100000000000000088817841970012523233890533447265625

base/multidimensional.jl

@@ -211,6 +211,28 @@ module IteratorsMD
     CartesianIndex(1, 2)
     ```
 
+    ## Broadcasting
+
+    `CartesianIndices` support broadcasting arithmetic (+ and -) with a `CartesianIndex`.
+
+    !!! compat "Julia 1.1"
+        Broadcasting of CartesianIndices requires at least Julia 1.1.
+
+    ```jldoctest
+    julia> CIs = CartesianIndices((2:3, 5:6))
+    2×2 CartesianIndices{2,Tuple{UnitRange{Int64},UnitRange{Int64}}}:
+     CartesianIndex(2, 5)  CartesianIndex(2, 6)
+     CartesianIndex(3, 5)  CartesianIndex(3, 6)
+
+    julia> CI = CartesianIndex(3, 4)
+    CartesianIndex(3, 4)
+
+    julia> CIs .+ CI
+    2×2 CartesianIndices{2,Tuple{UnitRange{Int64},UnitRange{Int64}}}:
+     CartesianIndex(5, 9)  CartesianIndex(5, 10)
+     CartesianIndex(6, 9)  CartesianIndex(6, 10)
+    ```
+
     For cartesian to linear index conversion, see [`LinearIndices`](@ref).
     """
     struct CartesianIndices{N,R<:NTuple{N,AbstractUnitRange{Int}}} <: AbstractArray{CartesianIndex{N},N}
@@ -228,6 +250,26 @@ module IteratorsMD
 
     CartesianIndices(A::AbstractArray) = CartesianIndices(axes(A))
 
+    """
+        (:)(I::CartesianIndex, J::CartesianIndex)
+
+    Construct [`CartesianIndices`](@ref) from two `CartesianIndex`.
+
+    !!! compat "Julia 1.1"
+        This method requires at least Julia 1.1.
+
+    # Examples
+    ```jldoctest
+    julia> I = CartesianIndex(2,1);
+
+    julia> J = CartesianIndex(3,3);
+
+    julia> I:J
+    2×3 CartesianIndices{2,Tuple{UnitRange{Int64},UnitRange{Int64}}}:
+     CartesianIndex(2, 1)  CartesianIndex(2, 2)  CartesianIndex(2, 3)
+     CartesianIndex(3, 1)  CartesianIndex(3, 2)  CartesianIndex(3, 3)
+    ```
+    """
     (:)(I::CartesianIndex{N}, J::CartesianIndex{N}) where N =
         CartesianIndices(map((i,j) -> i:j, Tuple(I), Tuple(J)))
 
@@ -672,6 +714,9 @@ Finite difference operator on a vector or a multidimensional array `A`. In the
 latter case the dimension to operate on needs to be specified with the `dims`
 keyword argument.
 
+!!! compat "Julia 1.1"
+    `diff` for arrays with dimension higher than 2 requires at least Julia 1.1.
+
 # Examples
 ```jldoctest
 julia> a = [2 4; 6 16]

base/namedtuple.jl

@@ -223,6 +223,10 @@ contains that field. Fields present in only the rightmost named tuple of a pair
 A fallback is implemented for when only a single named tuple is supplied,
 with signature `merge(a::NamedTuple)`.
 
+!!! compat "Julia 1.1"
+    Merging 3 or more `NamedTuple` requires at least Julia 1.1.
+
+# Examples
 ```jldoctest
 julia> merge((a=1, b=2, c=3), (b=4, d=5))
 (a = 1, b = 4, c = 3, d = 5)

base/parse.jl

@@ -14,6 +14,9 @@ of the form `"R±Iim"` as a `Complex(R,I)` of the requested type; `"i"` or `"j"`
 used instead of `"im"`, and `"R"` or `"Iim"` are also permitted.
 If the string does not contain a valid number, an error is raised.
 
+!!! compat "Julia 1.1"
+    `parse(Bool, str)` requires at least Julia 1.1.
+
 # Examples
 ```jldoctest
 julia> parse(Int, "1234")

base/path.jl

@@ -210,6 +210,9 @@ Split a file path into all its path components. This is the opposite of
 `joinpath`. Returns an array of substrings, one for each directory or file in
 the path, including the root directory if present.
 
+!!! compat "Julia 1.1"
+    This function requires at least Julia 1.1.
+
 # Examples
 ```jldoctest
 julia> splitpath("/home/myuser/example.jl")

base/process.jl

@@ -749,6 +749,9 @@ kill(p::Process) = kill(p, SIGTERM)
     getpid(process) -> Int32
 
 Get the child process ID, if it still exists.
+
+!!! compat "Julia 1.1"
+    This function requires at least Julia 1.1.
 """
 function Libc.getpid(p::Process)
     ppid = Int32(0)

base/range.jl

@@ -60,6 +60,9 @@ automatically such that the elements are `step` spaced (a [`StepRange`](@ref)).
 
 `stop` may be specified as either a positional or keyword argument.
 
+!!! compat "Julia 1.1"
+    `stop` as a positional argument requires at least Julia 1.1.
+
 # Examples
 ```jldoctest
 julia> range(1, length=100)

base/reflection.jl

@@ -256,6 +256,9 @@ end
 Construct a dictionary of the names (as symbols) and values of all local
 variables defined as of the call site.
 
+!!! compat "Julia 1.1"
+    This macro requires at least Julia 1.1.
+
 # Examples
 ```jldoctest
 julia> let x = 1, y = 2
@@ -664,6 +667,9 @@ end
 
 The declared types of all fields in a composite DataType `T` as a tuple.
 
+!!! compat "Julia 1.1"
+    This function requires at least Julia 1.1.
+
 # Examples
 ```jldoctest
 julia> struct Foo

base/some.jl

@@ -45,6 +45,9 @@ notnothing(::Nothing) = throw(ArgumentError("nothing passed to notnothing"))
     isnothing(x)
 
 Return `true` if `x === nothing`, and return `false` if not.
+
+!!! compat "Julia 1.1"
+    This function requires at least Julia 1.1.
 """
 isnothing(::Any) = false
 isnothing(::Nothing) = true

base/sort.jl

@@ -992,6 +992,9 @@ See [`sort!`](@ref) for a description of possible keyword arguments.
 
 To sort slices of an array, refer to [`sortslices`](@ref).
 
+!!! compat "Julia 1.1"
+    This function requires at least Julia 1.1.
+
 # Examples
 ```jldoctest
 julia> A = [4 3; 1 2]

base/util.jl

@@ -399,7 +399,16 @@ printstyled(io::IO, msg...; bold::Bool=false, color::Union{Int,Symbol}=:normal)
     with_output_color(print, color, io, msg...; bold=bold)
 printstyled(msg...; bold::Bool=false, color::Union{Int,Symbol}=:normal) =
     printstyled(stdout, msg...; bold=bold, color=color)
+"""
+    Base.julia_cmd(juliapath=joinpath(Sys.BINDIR::String, julia_exename()))
+
+Return a julia command similar to the one of the running process.
+Propagates the `--cpu-target`, `--sysimage`, --compile `, `--depwarn`
+and `--inline` command line arguments.
 
+!!! compat "Julia 1.1"
+    The `--inline` flag is only propagated in Julia 1.1 and later.
+"""
 function julia_cmd(julia=joinpath(Sys.BINDIR::String, julia_exename()))
     opts = JLOptions()
     cpu_target = unsafe_string(opts.cpu_target)
@@ -642,6 +651,10 @@ Inner constructors can still be defined, but at least one should accept argument
 same form as the default inner constructor (i.e. one positional argument per field) in
 order to function correctly with the keyword outer constructor.
 
+!!! compat "Julia 1.1"
+    `Base.@kwdef` for parametric structs, and structs with supertypes
+    requires at least Julia 1.1.
+
 # Examples
 ```jldoctest
 julia> Base.@kwdef struct Foo