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
Merged

Conversation

fredrikekre
Copy link
Member

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 domain:docs This change adds or pertains to documentation label Dec 1, 2018
@fredrikekre fredrikekre added this to the 1.1 milestone Dec 1, 2018
@StefanKarpinski
Copy link
Sponsor Member

OMG, you two are saints!

@mortenpi
Copy link
Contributor

mortenpi 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 mentioned this pull request Dec 3, 2018
@JeffBezanson
Copy link
Sponsor Member

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
Copy link
Sponsor Member

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

@mortenpi
Copy link
Contributor

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

NEWS.md Outdated Show resolved Hide resolved
base/multidimensional.jl Outdated Show resolved Hide resolved
@mbauman
Copy link
Sponsor Member

mbauman 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 Compare December 5, 2018 00:15
fredrikekre added a commit that referenced this pull request Dec 5, 2018
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>
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 merged commit 6175bd9 into master Dec 5, 2018
@fredrikekre fredrikekre deleted the fe/annotations branch December 5, 2018 09:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
domain:docs This change adds or pertains to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

6 participants