DOC: Update v1.3.0 changelog to reflect breaking change in join dtypes
State: closed

Minor update to old docs to reflect a change in how dtype is chosen in joins. Docs only.

- [ * ] closes #47384 
- [ n/a ] [Tests added and passed](https://pandas.pydata.org/pandas-docs/dev/development/contributing_codebase.html#writing-tests) if fixing a bug or adding a new feature
- [ n/a ] All [code checks passed](https://pandas.pydata.org/pandas-docs/dev/development/contributing_codebase.html#pre-commit).
- [ n/a ] Added [type annotations](https://pandas.pydata.org/pandas-docs/dev/development/contributing_codebase.html#type-hints) to new arguments/methods/functions.
- [ n/a ] Added an entry in the latest `doc/source/whatsnew/vX.X.X.rst` file if fixing a bug or adding a new feature.


Labels:

Comments:
We have float now, which I think is correct. So would agree with bugfix
ok @jreback  if this was intentional bug fix then policy would be to not back fix docs? I did check a few changelogs in 1.3 series and didn't see any bug fix that seemed to apply. 
It appears that there has been subsequent bug fix. In the change that was original reported between 1.2.5 and 1.3, the frame we use to set dtype swapped from right to left, but we didn't always get float on int joined to float. In master, we do. So, there may have been a breaking change in 1.3 series but it's superseded by a better bug fix between then and master. I haven't checked whether _that_ change is in docs, but that seems to argue to close original issue and close this PR?

Thanks for the help with this @guyrt. I think there are couple of things being mixed in the original issue, if I'm understanding things correctly.

It's reported that there is no example in the docstring of `DataFrame.join` that shows what happens when joining with different types (int and join). That seems reasonable to add, we can create an issue specific to this.

Then, since you found the line that caused this change on behavior, you can probably run `git blame` on it, find the commit/PR/issue that implemented that change, and confirm if that was intentional. If it was, I think we can close this PR and the original ticket. If it's not, we can probably still close both, but open a new issue with the unwanted change in behavior, so it can be discussed there if we want to keep it, revert it, or what.

Does this make sense to you?
Sorry for slow response on this - took a little covid induced downtime :)

Two thoughts:
1) Our current behavior is different than v1.3.0, and it's more correct! Now, we correctly type int joined to float to float, and it works whether you do x.join(y) or y.join(x). So, I think it's less useful to do a historical analysis as original item suggests. I propose closing both this PR and that issue.
2) I _do_ think that we should provide some updates in the join detailing what types one should expect for `DataFrame.join` with examples. @datapythonista  if you agree then please open an issue and assign to me and I'm happy to update those docs. 
Adding examples to show how joins with these types work sounds great. Maybe you can have a look at both the `join` docstring and the user guide about joins, and see where do you think it makes more sense to add (and you can link one from the other too).

You can create the issue yourself, I think you'll be able to detail better what you plan to do.
Thinking again about this, I'm not sure if it's a great idea to add an example of joining int and float to the docs. While it's nice to now have a more reasonable behavior, I think joining with a float column is a bad practice, and I'd personally make the operation fail. While this is a different discussion, I don't think showing how to join float-float types or int-float shouldn't be in our docs, as we shouldn't encourage it.