REL/DOC: more clear documentation of api changes in whatsnew

[jorisvandenbossche]

Sorry, long issue :-)

In issue #7750 there was some heated discussion about backwards compatibility and the fact we did or did not care enough about it. I don't want to start a new discussion on that topic again, rest assured (or not now :-)), but notwithstanding the at some point rather personal attacks in that discussion, I think we still should look at what we can learn from it.
And what I learned is that we can do a better job at documenting backward incompatible changes.

• We have no clear overview of these changes (and I am really speaking about 'changes for which users will have to change their code to keep it running/working correctly')
• In the whatsnew docs, there is the "API changes" section, which you could assume is about such kind of changes. In practice however, we made it a mix of enhancements (which are of course also api changes in se, as they 'change (add to) the api', but that fact is not really relevant) and breaking api changes.
  • eg the current api changes section: http://pandas-docs.github.io/pandas-docs-travis/whatsnew.html#api-changes. Second point (addition of level keyword) is an enhancement, not a breaking api change, as with a lot of the other bullet points. For this reason, the 'real' breaking api changes disappear a bit between all the others.
• deprecations are in a seperate section, but are also a kind of api changes

---

What I propose:

1. a better stuctured whatsnew, with a more strict structure
2. limit the 'API changes' section to backwards incompatible changes, the rest are new features/enhancements (keep a clear distinction)
3. for each backwards incompatible change, very clearly explain: what was the previous behaviour? what is the new behaviour? How can I keep the old behaviour? What should I do to update my code to keep it working?

Some examples of other libraries: Scipy speaks about "Backwards incompatible changes" (http://docs.scipy.org/doc/scipy-0.14.0/reference/release.0.14.0.html), scikit-learn about "API changes summary" (http://scikit-learn.org/stable/whats_new.html), sqlalchemy about "Behavioral changes" (http://docs.sqlalchemy.org/en/rel_0_9/changelog/migration_09.html#behavioral-changes-orm-09) and matlab about "Compatibility considerations" (http://www.mathworks.nl/help/matlab/release-notes.html).

A possible structure (in the past, in pandas there was also a more rigid structure with new features/api changes):

1. New features
     1.1 ... (subsections highlighting bigger new features)
     1.2 Categoricals
     1.3 Timedelta(Index)
     1.4 .dt accessor
     1.5 ....
2. Backwards incompatible API changes
     2.1 Breaking changes
     2.2 Deprecations
     2.3 Removal previously deprecated (prior version deprecations)
3. Other enhancements
4. Performance improvements
5. Bug fixes

For comparison, the current table of contents for 0.15 whatsnew

API changes
Memory Usage
.dt accessor
Timezone API changes
Rolling/Expanding Moments API changes
Internal Refactoring
Categoricals in Series/DataFrame
TimedeltaIndex/Scalar
Prior Version Deprecations/Changes
Deprecations
Enhancements
Performance
Bug Fixes

Some points of dicussion:

• 'api changes' section before new features instead of after?
• 'other enhancements' as subsection in 'new features'
• how to name the 'backwards incompatible API changes' (other options like behavioral changes, compatibility considerations, breaking API changes, ...)
• and of course the general idea I describe in this issue

Thoughts?

[jreback]

I think you could have a 2-level menu structure. But I wouldn't change the order much at all.

The most important part of the entire whatsnew is the very first page, the highlites, which allow one to jump to sections of relevance. Most people just jump around and don't read everything. Don't force one to go thru section by section (like the original whatsnew) and scipy etc, I think its a bad idea.

That said, I am pretty confident that the major backward incompatible changes are pretty clearly documented (via a warning box), where applicable in : Categorical, Timedelta, Index changes. Having these in a centralized section really doesn't serve much purpose.

And makes it MORE confusing. E.g. we have a section on Timezone API changes. None of these themselves are API breaking per se, but changes in behavior (none of which are back incompatible). They are a mix of bug fixes and enhancements, but are grouped logically.

Note that with the exception of Categorical which explicity warns you to audit your code etc. I don't think any of the changes in Timedelta, Index sub-classing are backward incompatible at all.

.

[jorisvandenbossche]

About "most people don't read everything" -> fully correct, but that is my point a bit: the breaking changes are now spread throughout the whatsnew, so if you want to know what these are, you have to read it all. For that, I think, a clear list of all 'real' breaking api changes would be helpful if you quickly want to skim through them to see if anything would be applicable for your personal code (i.e. "if you possibly have to fix something when going to upgrade"). Now there is no way to do this apart from going to all of the whatsnew docs.

I don't think this will be more confusing. Eg about your example about the Timezone API changes section: if they are not breaking changes, ok, the better!, but so they will not appear in this list of 'breaking' api changes and can just sit in a timezone section in the enhancements section. I fully in favor of having some subsection grouping related fixes/enhancements by topic as we now already do (that would be subsections in the enhancements section in my proposal above).

I am not saying we do a lot of backwards incompatible API changes. It is good that the changes in Timedelta, Index subclassin, categoricals, etc are mostly backwards compatible. But then they also don't belong in such a breaking API changes section. And we should make it more clear that this is the case. By now having a large section 'API changes' we give the impression of having a lot of 'breaking' api changes (I know that is not the same, but then we can just call it enhancements instead of api changes to make this more clear)

[jreback]

how about a compromise!

I like the subsection grouping (if u want to make a 2-level out of this as u suggested ok)

combine API and enhancements sections

then can make a backwards incompat API section which will be links if needed (eg the Categoical change , timedela compat issue, etc); like 1 line per change. might be a bit duplicative but ok I guess

so that this will be a comprehensive list of the backwards incompat API changes but we can still have logical groupings

[jorisvandenbossche]

good compromise!
and some duplication is not bad I think, as long as it makes it more clear.
I will try to come up with something next week.

[jreback]

updated whatsnew looks good! (maybe think about actually showing the 3rd level in the menu )