ARROW-5998: [Java] Open a document to track the API changes

[liyafan82]

We need a document to track the API behavior changes, so as not forget about them for the next release.

[codecov-io]

Codecov Report

Merging #4918 into master will increase coverage by 2.14%.
The diff coverage is n/a.

@@            Coverage Diff            @@
##           master   #4918      +/-   ##
=========================================
+ Coverage   87.46%   89.6%   +2.14%     
=========================================
  Files         994     660     -334     
  Lines      140389   96546   -43843     
  Branches     1418       0    -1418     
=========================================
- Hits       122785   86509   -36276     
+ Misses      17242   10037    -7205     
+ Partials      362       0     -362

Impacted Files	Coverage Δ
cpp/src/arrow/json/converter.cc	90.53% <0%> (-1.78%)	⬇️
cpp/src/arrow/json/chunked-builder.cc	79.91% <0%> (-1.68%)	⬇️
cpp/src/plasma/thirdparty/ae/ae.c	70.75% <0%> (-0.95%)	⬇️
r/src/recordbatch.cpp
r/R/Table.R
js/src/util/fn.ts
go/arrow/array/bufferbuilder.go
r/src/symbols.cpp
rust/datafusion/src/execution/projection.rs
rust/datafusion/src/execution/filter.rs
... and 327 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 85fe336...4c05293. Read the comment docs.

[tianchen92]

Thanks for doing this @liyafan82, I also have several PRs introducing new APIs which I think should added into this file after this merged.

[liyafan82]

Thanks for doing this @liyafan82, I also have several PRs introducing new APIs which I think should added into this file after this merged.

@tianchen92 thanks for your comments.
According to my understanding, this document should track APIs whose behaviors change. New APIs need not be included.

[emkornfield]

Maybe we should just start the blog post doc for the next release early? @nealrichardson ?

[nealrichardson]

I'm generally +100 for starting release announcements early--helps to make sure you ship something worth announcing. So I'd be in favor of that, though this seems more like a changelog that should exist separately anyway. Is there a convention for how/where to include changelogs with Java libraries? Seems like a useful thing to have, not just as a scratchpad for the next release announcement but to grow with the project.

[emkornfield]

I thought change logs were generated from jira automatically?

[nealrichardson]

For the release announcements, yeah they are autogenerated. I mean a human-curated running changelog specific for the Java library, for API changes and new features. Maybe that's not common in Java but it's standard practice in the R world (e.g. https://dplyr.tidyverse.org/news/), FWIW.

[wesm]

Maintaining this document could definitely grow onerous, though hopefully there aren't too many instances of breaking API changes that it becomes that way

[nealrichardson]

I've found it more valuable than onerous in maintaining this "NEWS" file in my projects. It encourages you to communicate important user-facing changes to your library's users, and those are generally at a lower level than you'd want in an Apache Arrow project release announcement. Just my USD 0.02.

[emkornfield]

+1 LGTM.