Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

News and compatibility annotations for Julia 1.1 #30230

Merged
merged 1 commit into from Dec 5, 2018

Conversation

6 participants
@fredrikekre
Copy link
Member

commented Dec 1, 2018

Me and @mortenpi have gone through the ~570 PRs that have been merged since Julia 1.0 (https://docs.google.com/spreadsheets/d/1PThPlhFwlkcmmEpe8JcJ-XyTdU-I1lmEh7iCw8AvFSM/edit?usp=sharing20) in preparation for the 1.1 release. We have added news and compatibility annotations for changes worthy of that.

Since we now have one doc for all of Julia 1.X (#26825) we have thus added small !!! compat notes to the manual for e.g. new functions and new behaviors. For a taste of what these annotations look like see e.g. https://julialang.github.io/Pkg.jl/dev/registries/

Walking through the PRs like this is not very efficient (and pretrty boring), so for future features I ask people to add these annotations together with NEWS.

@fredrikekre fredrikekre added the doc label Dec 1, 2018

@fredrikekre fredrikekre added this to the 1.1 milestone Dec 1, 2018

@fredrikekre fredrikekre force-pushed the fe/annotations branch from 9d444a6 to 6ecf58e Dec 1, 2018

@StefanKarpinski

This comment has been minimized.

Copy link
Member

commented Dec 2, 2018

OMG, you two are saints!

@mortenpi

This comment has been minimized.

Copy link
Contributor

commented Dec 3, 2018

so for future features I ask people to add these annotations together with NEWS.

Should we add a note to CONTRIBUTING.md? Something along the lines of:

#### Annotations for new features, deprecations and behaviour 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 where the change was made 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.
```

@fredrikekre fredrikekre referenced this pull request Dec 3, 2018

Merged

NEWS for #29749 #30245

@JeffBezanson

This comment has been minimized.

Copy link
Member

commented Dec 3, 2018

This is amazing. I was just starting to worry about how we were going to do this for this release and who was going to do it (me?) but now here it is :)

@StefanKarpinski

This comment has been minimized.

Copy link
Member

commented Dec 3, 2018

I cannot emphasize how wonderful it is that you two did this. Thank you sooo much! ❤️❤️❤️

@mortenpi

This comment has been minimized.

Copy link
Contributor

commented Dec 3, 2018

@mbauman suggested using a different icon (arrow-circle-up) for the compat notes. For that we just need to add this to the CSS:

.admonition.compat > .admonition-title:before {
    font-family: "FontAwesome";
    content: "\f0aa";
}

The same change needs to be done in Pkg as well to keep the style consistent.

Show resolved Hide resolved NEWS.md Outdated

@fredrikekre fredrikekre force-pushed the fe/annotations branch from 6ecf58e to a02ba64 Dec 3, 2018

Show resolved Hide resolved base/multidimensional.jl Outdated
@mbauman

This comment has been minimized.

Copy link
Member

commented Dec 4, 2018

It's not a very strong preference — which is why I figured I'd raise the possibility on slack instead of here. My thought is just to differentiate things a bit more from warnings, but the green does a pretty good job of that. And we also use the encircled ! for !!! notes, too, so let's not worry about the color of this 🚲🏠 too much.

@fredrikekre fredrikekre force-pushed the fe/annotations branch 3 times, most recently from 31eaaaa to cceb675 Dec 4, 2018

fredrikekre added a commit that referenced this pull request Dec 5, 2018

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

@fredrikekre fredrikekre force-pushed the fe/annotations branch from cceb675 to ebbabf5 Dec 5, 2018

@fredrikekre fredrikekre merged commit 6175bd9 into master Dec 5, 2018

3 checks passed

continuous-integration/appveyor/pr AppVeyor build succeeded
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details
julia freebsd ci Build done
Details

@fredrikekre fredrikekre deleted the fe/annotations branch Dec 5, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.