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>

Author: fredrikekre

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)