Skip to content

Commit

Permalink
Compat admonitions and NEWS for Julia 1.1 (#30230)
Browse files Browse the repository at this point in the history
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>
  • Loading branch information
3 people authored Dec 5, 2018
1 parent 6594acc commit 6175bd9
Show file tree
Hide file tree
Showing 35 changed files with 318 additions and 10 deletions.
15 changes: 15 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

This comment has been minimized.

Copy link
@PallHaraldsson

PallHaraldsson Dec 25, 2018

Contributor

extra word: made

This comment has been minimized.

Copy link
@KristofferC

KristofferC Dec 25, 2018

Member

Please just open an issue or preferably a PR instead of comment on a commit.

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).*
Expand Down
91 changes: 90 additions & 1 deletion NEWS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
------------------------
Expand All @@ -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]).
Expand All @@ -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
---------------------
Expand All @@ -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
4 changes: 4 additions & 0 deletions base/abstractarray.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down
3 changes: 3 additions & 0 deletions base/channels.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
4 changes: 4 additions & 0 deletions base/char.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
3 changes: 3 additions & 0 deletions base/error.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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))
Expand Down
3 changes: 3 additions & 0 deletions base/locks.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
5 changes: 5 additions & 0 deletions base/mpfr.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
45 changes: 45 additions & 0 deletions base/multidimensional.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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}
Expand All @@ -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)))

Expand Down Expand Up @@ -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]
Expand Down
4 changes: 4 additions & 0 deletions base/namedtuple.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
3 changes: 3 additions & 0 deletions base/parse.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Expand Down
3 changes: 3 additions & 0 deletions base/path.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Expand Down
3 changes: 3 additions & 0 deletions base/process.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
3 changes: 3 additions & 0 deletions base/range.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
6 changes: 6 additions & 0 deletions base/reflection.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
3 changes: 3 additions & 0 deletions base/some.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 3 additions & 0 deletions base/sort.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down
13 changes: 13 additions & 0 deletions base/util.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand Down
Loading

0 comments on commit 6175bd9

Please sign in to comment.